From: <mie...@us...> - 2012-10-28 03:53:17
|
Revision: 8545 http://sourceforge.net/p/oorexx/code-0/8545 Author: miesfeld Date: 2012-10-28 03:53:14 +0000 (Sun, 28 Oct 2012) Log Message: ----------- more work on ooDialog doc Modified Paths: -------------- docs/trunk/oodialog/en-US/dialogControlObject.xml docs/trunk/oodialog/en-US/eventNotification.xml docs/trunk/oodialog/en-US/treeview.xml Modified: docs/trunk/oodialog/en-US/dialogControlObject.xml =================================================================== --- docs/trunk/oodialog/en-US/dialogControlObject.xml 2012-10-28 03:52:10 UTC (rev 8544) +++ docs/trunk/oodialog/en-US/dialogControlObject.xml 2012-10-28 03:53:14 UTC (rev 8545) @@ -1212,6 +1212,12 @@ </variablelist> </para> </listitem></varlistentry> + <varlistentry><term>controlObj</term> + <listitem> + <para> + The dialog control object representing the underlying control that recieved the keyboard character event notification. + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return:</emphasis></term> Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-10-28 03:52:10 UTC (rev 8544) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-10-28 03:53:14 UTC (rev 8545) @@ -4124,6 +4124,31 @@ <listitem> <para> The event keyword. Use exactly one of the following keywords, case is not significant: + </para> + <para> + <simplelist type='vert' columns='3'> + <member>ACTIVATE</member> + <member>BEGINDRAG</member> + <member>BEGINEDIT</member> + <member>BEGINRDRAG</member> + <member>ENDEDIT</member> + <member>CHANGING</member> + <member>CHANGED</member> + <member>CHECKBOXCHANGED</member> + <member>CLICK</member> + <member>COLUMNCLICK</member> + <member>DBLCLK</member> + <member>DELETE</member> + <member>DELETEALL</member> + <member>FOCUSCHANGED</member> + <member>GETINFOTIP</member> + <member>INSERTED</member> + <member>KEYDOWN</member> + <member>KEYDOWNEX</member> + <member>SELECTCHANGED</member> + <member>SELECTFOCUSCHANGED</member> + </simplelist> + </para> <variablelist> <varlistentry><term>ACTIVATE</term> <listitem> @@ -4138,6 +4163,12 @@ information on how to implement a drag-and-drop handler. </para> </listitem></varlistentry> + <varlistentry><term>BEGINEDIT</term> + <listitem> + <para> + Editing a label has been started. Do not connect this event if you are using the DEFAULTEDIT keyword. + </para> + </listitem></varlistentry> <varlistentry><term>BEGINRDRAG</term> <listitem> <para> @@ -4146,12 +4177,6 @@ handler. </para> </listitem></varlistentry> - <varlistentry><term>BEGINEDIT</term> - <listitem> - <para> - Editing a label has been started. Do not connect this event if you are using the DEFAULTEDIT keyword. - </para> - </listitem></varlistentry> <varlistentry><term>ENDEDIT</term> <listitem> <para> @@ -4200,6 +4225,12 @@ <xref linkend="mthConnectNotifyEvent"/> method's CLICK event. </para> </listitem></varlistentry> + <varlistentry><term>COLUMNCLICK</term> + <listitem> + <para> + In report view only, a column header has been clicked. Contrast this with the CLICK keyword. + </para> + </listitem></varlistentry> <varlistentry><term>DBLCLK</term> <listitem> <para> @@ -4208,12 +4239,6 @@ <xref linkend="mthConnectNotifyEvent"/> method's DBLCLK event. </para> </listitem></varlistentry> - <varlistentry><term>COLUMNCLICK</term> - <listitem> - <para> - In report view only, a column header has been clicked. Contrast this with the CLICK keyword. - </para> - </listitem></varlistentry> <varlistentry><term>DELETE</term> <listitem> <para> @@ -4253,6 +4278,18 @@ A key was pressed inside the list view. This notification is not sent while a label is being edited. </para> </listitem></varlistentry> + <varlistentry><term>KEYDOWNEX</term> + <listitem> + <para> + A key was pressed inside the list view. This notification is not sent while a label is being edited. + </para> + <para> + This event is exactly the same as the KEYDOWN event. Except, when this keyword is used, the ooDialog framework sends + a different set of arguments to the event handler. The additional arguments provide more information to the + programmer than the + arguments sent when the KEYDOWN keyword is used. The two keywords are needed to provide backwards compatibility. + </para> + </listitem></varlistentry> <varlistentry><term>SELECTCHANGED</term> <listitem> <para> @@ -4270,7 +4307,6 @@ </para> </listitem></varlistentry> </variablelist> - </para> </listitem></varlistentry> <varlistentry><term>methodName</term> <listitem> @@ -4365,62 +4401,42 @@ </listitem></varlistentry> </variablelist> -<section id="evtListViewCLICK" xreflabel="CLICK"><title>Click / Double Click Event Handler</title> -<indexterm><primary>ListView Event</primary><secondary>CLICK</secondary></indexterm> -<indexterm><primary>ListView Event</primary><secondary>DBLCLK</secondary></indexterm> +<section id="evtListViewBEGINDRAG" xreflabel="BEGINDRAG"><title>BeginDrag Event Handler</title> +<indexterm><primary>ListView Event</primary><secondary>BEGINDRAG</secondary></indexterm> + <para> - The event handling method for the CLICK event is invoked when the user clicks on the list-view with the left mouse. - The event handler for the DBLCLK is invoked when the user double clicks on the list-view. This excludes the column - headers in report view. Both event handlers receive the same arguments. + The event-handling method connected to BEGINDRAG receives three arguments: the control ID of the list-view control, + the index of the list item to be dragged, and the point where the mouse cursor was pressed (x and y positions, + separated by a blank). </para> + +<programlisting> +<![CDATA[ +::method onBeginDrag unguarded + use arg id, item, where + + return 0 +]]> +</programlisting> +</section> + +<section id="evtListViewBEGINRDRAG" xreflabel=""><title>BeginRDrag Event Handler</title> +<indexterm><primary>ListView Event</primary><secondary>BEGINRDRAG</secondary></indexterm> + <para> - Note that the user can click on a list-view item, or on the background of the list view. When the click is on the - background of the list-view then both the <emphasis role="italic">itemIndex</emphasis> and <emphasis - role="italic">columnIndex</emphasis> will be -1. The method will receive four arguments: + The event-handling method connected to BEGINRDRAG receives three arguments: the control ID of the list-view control, + the index of the list item to be dragged, and the point where the mouse cursor was pressed (x and y positions, + separated by a blank). </para> <programlisting> <![CDATA[ - ::method onClick unguarded - use arg id, itemIndex, columnIndex, keyState +::method onBeginRightDrag unguarded + use arg id, item, where - return 0 + return 0 ]]> </programlisting> - -<variablelist> - <varlistentry><term>id</term> - <listitem> - <para> - The resource ID of the list-view control whose item was clicked. - </para> - </listitem></varlistentry> - <varlistentry><term>itemIndex</term> - <listitem> - <para> - The zero-based index of the item that was clicked, or -1 if the background of the list-view was clicked. In report - view this is often thought of as the row index. - </para> - </listitem></varlistentry> - <varlistentry><term>columnIndex</term> - <listitem> - <para> - The zero-based index of the subitem that was clicked, or -1 if the click was on the background of the list view. In - report view this is often thought of as the column of row. In all views other than report view, this arg will always - be 0. - </para> - </listitem></varlistentry> - <varlistentry><term>keyState</term> - <listitem> - <para> - This argument reports the state of the shift, control, and alt keys at the time of the mouse click. The argument is - a string of keywords separated by blanks. The keywords consist of: SHIFT, CONTROL, ALT, or NONE. The presence of a - keyword indicates the key was held down when the user clicked on the list-view control. NONE of course indicates - that none of the keys were down. If the user managed to hold all three of the keys down at the time of the mouse - click, the argument would be the string: <emphasis role="italic">SHIFT CONTROL ALT</emphasis>. - </para> - </listitem></varlistentry> -</variablelist> </section> <section id="evtListViewCHECKBOXCHANGED" xreflabel="CHECKBOXCHANGED"><title>CheckBoxChanged Event Handler</title> @@ -4495,19 +4511,26 @@ </section> <!-- End CheckBoxChanged Event Handler --> -<section id="evtListViewSELECTCHANGE" xreflabel="SELECTCHANGE"><title>SelectChange Event Handler</title> -<indexterm><primary>ListView Event</primary><secondary>SELECTCHANGE</secondary></indexterm> +<section id="evtListViewCLICK" xreflabel="CLICK"><title>Click / Double Click Event Handler</title> +<indexterm><primary>ListView Event</primary><secondary>CLICK</secondary></indexterm> +<indexterm><primary>ListView Event</primary><secondary>DBLCLK</secondary></indexterm> <para> - The event handler for the selection changed event is invoked when the selection state of an item changes. The method - receives three arguments: + The event handling method for the CLICK event is invoked when the user clicks on the list-view with the left mouse. + The event handler for the DBLCLK is invoked when the user double clicks on the list-view. This excludes the column + headers in report view. Both event handlers receive the same arguments. </para> +<para> + Note that the user can click on a list-view item, or on the background of the list view. When the click is on the + background of the list-view then both the <emphasis role="italic">itemIndex</emphasis> and <emphasis + role="italic">columnIndex</emphasis> will be -1. The method will receive four arguments: +</para> <programlisting> <![CDATA[ -::method onSelectChanged unguarded - use arg id, itemIndex, state + ::method onClick unguarded + use arg id, itemIndex, columnIndex, keyState - return 0 + return 0 ]]> </programlisting> @@ -4515,106 +4538,56 @@ <varlistentry><term>id</term> <listitem> <para> - The resource ID of the list-view control whose item had the selection changed. + The resource ID of the list-view control whose item was clicked. </para> </listitem></varlistentry> <varlistentry><term>itemIndex</term> <listitem> <para> - The index of the item whose selection was changed. + The zero-based index of the item that was clicked, or -1 if the background of the list-view was clicked. In report + view this is often thought of as the row index. </para> </listitem></varlistentry> - <varlistentry><term>state</term> + <varlistentry><term>columnIndex</term> <listitem> <para> - This argument reports whether the item was selected or unselected. Its value will be either - "SELECTED" or "UNSELECTED" + The zero-based index of the subitem that was clicked, or -1 if the click was on the background of the list view. In + report view this is often thought of as the column of row. In all views other than report view, this arg will always + be 0. </para> </listitem></varlistentry> -</variablelist> -</section> - -<section id="evtListViewFOCUSCHANGED" xreflabel="FOCUSCHANGED"><title>FocusChanged Event Handler</title> -<indexterm><primary>ListView Event</primary><secondary>FOCUSCHANGED</secondary></indexterm> -<para> - The event handler for the focus changed event is invoked when an item gains or loses focus. The method receives three - arguments: -</para> - -<programlisting> -<![CDATA[ -::method onFocusChanged unguarded - use arg id, itemIndex, state - - return 0 -]]> -</programlisting> -<variablelist> - <varlistentry><term>id</term> + <varlistentry><term>keyState</term> <listitem> <para> - The resource ID of the list-view control whose item had the focus changed. + This argument reports the state of the shift, control, and alt keys at the time of the mouse click. The argument is + a string of keywords separated by blanks. The keywords consist of: SHIFT, CONTROL, ALT, or NONE. The presence of a + keyword indicates the key was held down when the user clicked on the list-view control. NONE of course indicates + that none of the keys were down. If the user managed to hold all three of the keys down at the time of the mouse + click, the argument would be the string: <emphasis role="italic">SHIFT CONTROL ALT</emphasis>. </para> </listitem></varlistentry> - <varlistentry><term>itemIndex</term> - <listitem> - <para> - The index of the item which gained or lost the focus. - </para> - </listitem></varlistentry> - <varlistentry><term>state</term> - <listitem> - <para> - This argument reports whether the focus was gained or lost. Its value will be either "FOCUSED" or - "UNFOCUSED" - </para> - </listitem></varlistentry> </variablelist> </section> -<section id="evtListViewSELECTFOCUSCHANGED" xreflabel="SELECTFOCUSCHANGED"><title>SelectFocusChanged Event Handler</title> -<indexterm><primary>ListView Event</primary><secondary>SELECTFOCUSCHANGED</secondary></indexterm> +<section id="evtListViewCOLUMNCLICK" xreflabel="COLUMNCLICK"><title>ColumnClick Event Handler</title> +<indexterm><primary>ListView Event</primary><secondary>COLUMNCLICK</secondary></indexterm> <para> - The event handle for the selection or focus changed event is invoked when either the selection or the focus of an item - changes. The method receives 3 arguments: + The event-handling method connected to COLUMNCLICK receives two arguments: the control ID of the list-view control and + the zero-based column number of which the header button was pressed. </para> <programlisting> <![CDATA[ -::method onSelectFocusChanged unguarded - use arg id, itemIndex, state +::method onColumnClick unguarded + use arg id, column return 0 ]]> </programlisting> -<variablelist> - <varlistentry><term>id</term> - <listitem> - <para> - The resource ID of the list-view control whose item had the either the focus or the selection changed. - </para> - </listitem></varlistentry> - <varlistentry><term>itemIndex</term> - <listitem> - <para> - The index of the item where the state was changed. - </para> - </listitem></varlistentry> - <varlistentry><term>state</term> - <listitem> - <para> - This argument reports whether the focus was gained or lost and whether the selection was gained or lost. Its - value will contain at least one of the keywords: "SELECTED", "UNSELECTED", - "FOCUSED" or "UNFOCUSED". It is possible for both the selection and focus changed to be - reported at once, however sometimes each change is reported separately. (This has nothing to do with ooDialog, - it is how the operating system sends the messages.) - </para> - </listitem></varlistentry> -</variablelist> - </section> + <section id="evtListViewENDEDIT" xreflabel="ENDEDIT"><title>EndEdit Event Handler</title> <indexterm><primary>ListView Event</primary><secondary>ENDEDIT</secondary></indexterm> <para> @@ -4633,25 +4606,6 @@ </section> -<section id="evtListViewCOLUMNCLICK" xreflabel="COLUMNCLICK"><title>ColumnClick Event Handler</title> -<indexterm><primary>ListView Event</primary><secondary>COLUMNCLICK</secondary></indexterm> -<para> - The event-handling method connected to COLUMNCLICK receives two arguments: the control ID of the list-view control and - the zero-based column number of which the header button was pressed. -</para> - -<programlisting> -<![CDATA[ -::method onColumnClick unguarded - use arg id, column - - return 0 -]]> -</programlisting> - -</section> - - <section id="evtListViewGETINFOTIP"><title>GetInfoTip Event Handler</title> <indexterm><primary>ListView Event</primary><secondary>GETINFOTIP</secondary></indexterm> <para> @@ -4773,42 +4727,328 @@ </section> -<section id="evtListViewBEGINDRAG" xreflabel="BEGINDRAG"><title>BeginDrag Event Handler</title> -<indexterm><primary>ListView Event</primary><secondary>BEGINDRAG</secondary></indexterm> +<section id="evtListViewKEYDOWNEX" xreflabel="KEYDOWNEX"><title>KeyDown (extended) Event Handler</title> +<indexterm><primary>ListView Event</primary><secondary>KEYDOWNEX</secondary></indexterm> +<para> + The event-handling method connected through the KEYDOWNEX keyword is similar to the event handler for the <link + linkend="evtListViewKEYDOWN">KeyDown</link> event handler. It is invoked for the same event, when the user presses a key + within the list-view. However, it receives a different set of arguments than that provided when the KEYDOWN keyword is + used. +</para> +<programlisting> +<![CDATA[ +::method onKeyDownEx unguarded + use arg vKey, isShift, isCtrl, isAlt, extraInfo, listViewObj + + return response +]]> +</programlisting> + +<variablelist> + <varlistentry><term><emphasis role="bold">Event Handler Method Arguments:</emphasis></term> + <listitem> + <para> + The event handling method receives 6 arguments: + </para> + <variablelist> + <varlistentry><term>vKey</term> + <listitem> + <para> + The virtual key code of of the key pressed. Use the <xref linkend="mthKey2Name"/> method of the <xref linkend="clsVK"/> + class to determine which key was pressed. + </para> + </listitem></varlistentry> + <varlistentry><term>isShift</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>isCtrl</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>isAlt</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>extended</term> + <listitem> + <para> + The character event is for one of the extended keys previously mentioned, INS, DEL, HOME, END, PAGE UP, PAGE + DOWN, or one of the arrow keys. + </para> + </listitem></varlistentry> + <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> + <varlistentry><term>listViewObj</term> + <listitem> + <para> + The Rexx <computeroutput>ListView</computeroutput> object whose underlying Windows list-view had the keydown event. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + When the <emphasis role="italic">willReply</emphasis> argument to the <link linkend="mthConnectListViewEvent"></link> + method is true, the event handler must return a value. However, the operating system ignores the return value, so any + value can be used. 0 makes a good return. + </para> + <para> + If <emphasis role="italic">willReply</emphasis> is false, the event handler does not <emphasis + role="italic">have</emphasis> to return a value, but good practice would be to always return a value from an event + handler. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example</emphasis></term> + <listitem> + <para> + The following example uses an event handler that deletes the selected item if the user presses the DEL key while holding + down the control key. The next item following the deleted item is then selected. However, if the deleted item is the last + item in the last, then the previous item is selected. If the deleted item is the last item in the list, then nothing is + selected: + +<programlisting> +<![CDATA[ + +::method onKeyDownEx unguarded + use arg vKey, isShift, isCtrl, isAlt, extraInfo, listViewObj + + if vKey == .VK~DELETE & isCtrl then do + selectedIndex = listView~selected + if selectedIndex <> -1 then do + listView~delete(selectedIndex) + if selectedIndex == listView~items then do + if selectedIndex == 0 then do + -- Do nothing, there are no items in the list-view now. + nop + end + else do + listView~select(selectedIndex - 1) + end + end + else do + listView~select(selectedIndex) + end + end + end + + return 0 +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> + +</section> + + +<section id="evtListViewFOCUSCHANGED" xreflabel="FOCUSCHANGED"><title>FocusChanged Event Handler</title> +<indexterm><primary>ListView Event</primary><secondary>FOCUSCHANGED</secondary></indexterm> <para> - The event-handling method connected to BEGINDRAG receives three arguments: the control ID of the list-view control, - the index of the list item to be dragged, and the point where the mouse cursor was pressed (x and y positions, - separated by a blank). + The event handler for the focus changed event is invoked when an item gains or loses focus. The method receives three + arguments: </para> <programlisting> <![CDATA[ -::method onBeginDrag unguarded - use arg id, item, where +::method onFocusChanged unguarded + use arg id, itemIndex, state return 0 ]]> </programlisting> +<variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The resource ID of the list-view control whose item had the focus changed. + </para> + </listitem></varlistentry> + <varlistentry><term>itemIndex</term> + <listitem> + <para> + The index of the item which gained or lost the focus. + </para> + </listitem></varlistentry> + <varlistentry><term>state</term> + <listitem> + <para> + This argument reports whether the focus was gained or lost. Its value will be either "FOCUSED" or + "UNFOCUSED" + </para> + </listitem></varlistentry> +</variablelist> </section> -<section id="evtListViewBEGINRDRAG" xreflabel=""><title>BeginRDrag Event Handler</title> -<indexterm><primary>ListView Event</primary><secondary>BEGINRDRAG</secondary></indexterm> +<section id="evtListViewSELECTCHANGE" xreflabel="SELECTCHANGE"><title>SelectChange Event Handler</title> +<indexterm><primary>ListView Event</primary><secondary>SELECTCHANGE</secondary></indexterm> +<para> + The event handler for the selection changed event is invoked when the selection state of an item changes. The method + receives three arguments: +</para> +<programlisting> +<![CDATA[ +::method onSelectChanged unguarded + use arg id, itemIndex, state + + return 0 +]]> +</programlisting> + +<variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The resource ID of the list-view control whose item had the selection changed. + </para> + </listitem></varlistentry> + <varlistentry><term>itemIndex</term> + <listitem> + <para> + The index of the item whose selection was changed. + </para> + </listitem></varlistentry> + <varlistentry><term>state</term> + <listitem> + <para> + This argument reports whether the item was selected or unselected. Its value will be either + "SELECTED" or "UNSELECTED" + </para> + </listitem></varlistentry> +</variablelist> +</section> + +<section id="evtListViewSELECTFOCUSCHANGED" xreflabel="SELECTFOCUSCHANGED"><title>SelectFocusChanged Event Handler</title> +<indexterm><primary>ListView Event</primary><secondary>SELECTFOCUSCHANGED</secondary></indexterm> <para> - The event-handling method connected to BEGINRDRAG receives three arguments: the control ID of the list-view control, - the index of the list item to be dragged, and the point where the mouse cursor was pressed (x and y positions, - separated by a blank). + The event handle for the selection or focus changed event is invoked when either the selection or the focus of an item + changes. The method receives 3 arguments: </para> <programlisting> <![CDATA[ -::method onBeginRightDrag unguarded - use arg id, item, where +::method onSelectFocusChanged unguarded + use arg id, itemIndex, state return 0 ]]> </programlisting> + +<variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The resource ID of the list-view control whose item had the either the focus or the selection changed. + </para> + </listitem></varlistentry> + <varlistentry><term>itemIndex</term> + <listitem> + <para> + The index of the item where the state was changed. + </para> + </listitem></varlistentry> + <varlistentry><term>state</term> + <listitem> + <para> + This argument reports whether the focus was gained or lost and whether the selection was gained or lost. Its + value will contain at least one of the keywords: "SELECTED", "UNSELECTED", + "FOCUSED" or "UNFOCUSED". It is possible for both the selection and focus changed to be + reported at once, however sometimes each change is reported separately. (This has nothing to do with ooDialog, + it is how the operating system sends the messages.) + </para> + </listitem></varlistentry> +</variablelist> + </section> </section> @@ -7183,7 +7423,28 @@ <varlistentry><term>event</term> <listitem> <para> - A keyword indicating which event is to be connected. The keyword must be one of the following: + A keyword indicating which event is to be connected. Case is not significant. The keyword must be one of the following: + </para> + <para> + <simplelist type='vert' columns='3'> + <member>BEGINDRAG</member> + <member>BEGINEDIT</member> + <member>BEGINRDRAG</member> + <member>DEFAULTEDIT</member> + <member>CHECKBOXCHANGED</member> + <member>CLICK</member> + <member>COLUMNCLICK</member> + <member>DELETE</member> + <member>ENDEDIT</member> + <member>EXPANDING</member> + <member>EXPANDED</member> + <member>GETINFOTIP</member> + <member>KEYDOWN</member> + <member>KEYDOWNEX</member> + <member>SELECTCHANGED</member> + <member>SELECTCHANGING</member> + </simplelist> + </para> <variablelist> <varlistentry><term>BEGINDRAG</term> <listitem> @@ -7193,6 +7454,12 @@ implement a drag-and-drop handler. </para> </listitem></varlistentry> + <varlistentry><term>BEGINEDIT</term> + <listitem> + <para> + Editing a label has been started. + </para> + </listitem></varlistentry> <varlistentry><term>BEGINRDRAG</term> <listitem> <para> @@ -7201,15 +7468,6 @@ implement a drag-and-drop handler. handler. </para> </listitem></varlistentry> - <varlistentry><term>BEGINEDIT</term> - <listitem><para>Editing a label has been started. - </para></listitem></varlistentry> - <varlistentry id="evtTreeViewENDEDIT"><term>ENDEDIT</term> - <listitem> - <para> - Label editing has ended. - </para> - </listitem></varlistentry> <varlistentry id="evtTreeViewDEFAULTEDIT"><term>DEFAULTEDIT</term> <listitem> <para> @@ -7222,6 +7480,18 @@ When you specify this event, the <emphasis role="italic">msgToRaise</emphasis> argument is ignored. </para> </listitem></varlistentry> + <varlistentry id="evtTreeViewENDEDIT"><term>ENDEDIT</term> + <listitem> + <para> + Label editing has ended. + </para> + </listitem></varlistentry> + <varlistentry><term>DELETE</term> + <listitem> + <para> + An item has been deleted. + </para> + </listitem></varlistentry> <varlistentry><term>EXPANDING</term> <listitem> <para> @@ -7241,22 +7511,22 @@ control has the <link linkend="styTreeViewInfoTip">INFOTIP</link> style. </para> </listitem></varlistentry> - <varlistentry><term>DELETE</term> + <varlistentry><term>KEYDOWN</term> <listitem> <para> - An item has been deleted. + A key was pressed inside the tree view. This notification is not sent while a label is being edited. </para> </listitem></varlistentry> - <varlistentry><term>KEYDOWN</term> + <varlistentry><term>KEYDOWNEX</term> <listitem> <para> A key was pressed inside the tree view. This notification is not sent while a label is being edited. </para> - </listitem></varlistentry> - <varlistentry><term>SELCHANGING</term> - <listitem> <para> - Another item is about to be selected. This notification is sent before the selection has changed. + This event is exactly the same as the KEYDOWN event. Except, when this keyword is used, the ooDialog framework sends + a different set of arguments to the event handler. The additional arguments provide more information to the + programmer than the arguments sent when the KEYDOWN keyword is used. The two keywords are needed to provide + backwards compatibility. </para> </listitem></varlistentry> <varlistentry><term>SELCHANGED</term> @@ -7265,8 +7535,13 @@ Another item was selected. This notification is sent after the selection was changed. </para> </listitem></varlistentry> + <varlistentry><term>SELCHANGING</term> + <listitem> + <para> + Another item is about to be selected. This notification is sent before the selection has changed. + </para> + </listitem></varlistentry> </variablelist> - </para> </listitem></varlistentry> <varlistentry><term>mthName</term> <listitem> @@ -7288,9 +7563,10 @@ </para> <para> <emphasis role="bold">Note:</emphasis> Currently the <emphasis role="italic">willReply</emphasis> argument is ignored - for all events except the EXPANDING and EXPANDED events. For all other events, the interpreter never waits for the - reply from the event handler. Future enhancements to the <computeroutput>TreeView</computeroutput> class may allow the - <emphasis role="italic">willReply</emphasis> to have effect for all tree-view event notifications. + for all events except the EXPANDING, EXPANDED, and KEYDOWNEX events. For the GETINFOTIP event, the interpreter always + waits for the reply. For all other events, the interpreter never waits for the reply from the event handler. Future + enhancements to the <computeroutput>TreeView</computeroutput> class may allow the <emphasis + role="italic">willReply</emphasis> to have effect for all tree-view event notifications. </para> </listitem></varlistentry> </variablelist> </listitem></varlistentry> @@ -7614,8 +7890,201 @@ </section> <!-- End GetInfoTip Event Handler --> -</section> +<section id="evtTreeViewKEYDOWNEX" xreflabel="KEYDOWNEX"><title>KeyDown (extended) Event Handler</title> +<indexterm><primary>TreeView Event</primary><secondary>KEYDOWNEX</secondary></indexterm> +<para> + The event-handling method connected through the KEYDOWNEX keyword is similar to the event handler for the KEYDOWN event + handler. It is invoked for the same event, when the user presses a key within the tree-view. However, it receives a + different set of arguments than that provided when the KEYDOWN keyword is used. +</para> +<programlisting> +<![CDATA[ +::method onKeyDownEx unguarded + use arg vKey, isShift, isCtrl, isAlt, extraInfo, treeViewObj + + return response +]]> +</programlisting> + +<variablelist> + <varlistentry><term><emphasis role="bold">Event Handler Method Arguments:</emphasis></term> + <listitem> + <para> + The event handling method receives 6 arguments: + </para> + <variablelist> + <varlistentry><term>vKey</term> + <listitem> + <para> + The virtual key code of of the key pressed. Use the <xref linkend="mthKey2Name"/> method of the <xref linkend="clsVK"/> + class to determine which key was pressed. + </para> + </listitem></varlistentry> + <varlistentry><term>isShift</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>isCtrl</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>isAlt</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 may be the empty string, otherwise it will contain some combination of these + keywords: + <variablelist> + <varlistentry><term>extended</term> + <listitem> + <para> + The key down event is for one of the extended keys. + </para> + </listitem></varlistentry> + <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> + <varlistentry><term>treeViewObj</term> + <listitem> + <para> + The Rexx <computeroutput>TreeView</computeroutput> object whose underlying Windows tree-view had the key down event. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + When the <emphasis role="italic">willReply</emphasis> argument to the <link linkend="mthConnectTreeViewEvent"></link> + method is true, the event handler must return a value. + </para> + <para> + If the key pressed was a character key, the character is used as part of an incremental search. The event handler returns + true to allow the character to be added to the incremental search and false to prevent the character from being added. If + the key pressed was not a character key, then the return is ignored by the operating system. 0 makes a good return when + the operating system ingores the return value. + </para> + <para> + If <emphasis role="italic">willReply</emphasis> is false, the event handler does not <emphasis + role="italic">have</emphasis> to return a value, but good practice would be to always return a value from an event + handler. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example</emphasis></term> + <listitem> + <para> + The following example allows the user to type Ctrl-Ins (control insert) to add a new item to the tree view: + +<programlisting> +<![CDATA[ + +::method onKeyDownEx unguarded + use arg vKey, isShift, isCtrl, isAlt, extraInfo, treeViewObj + + if vKey == .VK~INSERT, isCtrl then do + reply .false + + self~addNewItem(treeViewObj) + return + end + + return .true +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> + +</section> <!-- End KeyDownEx Event Handler --> + +</section> <!-- End EventNotification::connectTreeViewEvent() --> + + <section id="mthConnectUpDownEvent" xreflabel="connectUpDownEvent"><title>connectUpDownEvent</title> <indexterm><primary>connectUpDownEvent</primary></indexterm> <indexterm><primary>dialog object</primary><secondary>connectUpDownEvent</secondary></indexterm> Modified: docs/trunk/oodialog/en-US/treeview.xml =================================================================== --- docs/trunk/oodialog/en-US/treeview.xml 2012-10-28 03:52:10 UTC (rev 8544) +++ docs/trunk/oodialog/en-US/treeview.xml 2012-10-28 03:53:14 UTC (rev 8545) @@ -184,7 +184,7 @@ <entry>Gets the user data associated with the specified tree-view item.</entry> </row> <row> -<entry><xref linkend="mthGetItemTextClsTreeView"/></entry> +<entry><xref linkend="mthItemTextClsTreeView"/></entry> <entry>Gets the text, the label, of the specified tree-view item.</entry> </row> <row> @@ -1209,64 +1209,6 @@ </section> <!-- End TreeView::getItemData() --> -<section id="mthGetItemTextClsTreeView" xreflabel="getItemText"><title>getItemText</title> -<indexterm><primary>getItemText</primary></indexterm> -<indexterm><primary>TreeView class</primary><secondary>getItemText</secondary></indexterm> -<programlisting> -<![CDATA[ ->>--getItemText(--hItem--)----------------------->< -]]> -</programlisting> - -<para> - Retrieves the text of the specified tree-view item. -</para> -<variablelist> - <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> - <listitem> - <para> - The single argument is: - </para> - <variablelist> - <varlistentry><term>hItem [required]</term> - <listitem> - <para> - The tree-view item to retrieve the text from. - </para> - </listitem></varlistentry> - </variablelist> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> - <listitem> - <para> - The return is the text assigned to the specified tree-view item. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> - <listitem> - <para> - This example retrieves the text of the selected item: -<programlisting> -<![CDATA[ - - tv = self~newTreeVies(IDC_TV_BOOK) - - selectedItem = tv~selected - if selectedItem == 0 then do - say 'No item is selected' - end - else do - say 'The text for the selected item is:' tv~getItemText(selectedItem) - end - -]]> -</programlisting> - </para> - </listitem></varlistentry> -</variablelist> -</section> <!-- End TreeView::getItemText() --> - - <section id="hittest"><title>HitTest</title> <indexterm><primary>HitTest</primary></indexterm> <programlisting> @@ -1953,6 +1895,64 @@ </variablelist> </section> +<section id="mthItemTextClsTreeView" xreflabel="itemText"><title>itemText</title> +<indexterm><primary>itemText</primary></indexterm> +<indexterm><primary>TreeView class</primary><secondary>itemText</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--itemText(--hItem--)-------------------------->< +]]> +</programlisting> + +<para> + Retrieves the text of the specified tree-view item. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The single argument is: + </para> + <variablelist> + <varlistentry><term>hItem [required]</term> + <listitem> + <para> + The tree-view item to retrieve the text from. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + The return is the text assigned to the specified tree-view item. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example retrieves the text of the selected item: +<programlisting> +<![CDATA[ + + tv = self~newTreeVies(IDC_TV_BOOK) + + selectedItem = tv~selected + if selectedItem == 0 then do + say 'No item is selected' + end + else do + say 'The text for the selected item is:' tv~itemText(selectedItem) + end + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End TreeView::itemText() --> + + <section id="makefirstvisibletrc"><title>MakeFirstVisible</title> <indexterm><primary>MakeFirstVisible</primary> <secondary>TreeView class</secondary></indexterm> @@ -2764,11 +2764,11 @@ <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - The list-view control allows the user (the Rexx programmer) to associate a data value with any, or all, of the - list-view items. The data value can be any ooRexx object. The data value can be retrieved without removing it from a - list-view item through the <xref linkend="mthGetItemDataClsListView"/> method, or it can be removed through - the <xref linkend="mthRemoveItemDataClsListView"/>. Storing a user value for each item can be useful in any - number of ways. One specific use is in the <xref linkend="mthSortItems"/> method. + The tree-view control allows the user (the Rexx programmer) to associate a data value with any, or all, of the tree-view + items. The data value can be any ooRexx object. The data value can be retrieved without removing it from a + list-view item through the <xref linkend="mthGetItemDataClsTreeView"/> method, or it can be removed through the <xref + linkend="mthRemoveItemDataClsTreeView"/>. Storing a user value for each item can be useful in any number of ways. One + specific use is in the <xref linkend="mthSortChildrenCB"/> method. </para> <para> It is possible, although very unlikely, that there will be an error in the tree-view control when setting the user data. |
From: <mie...@us...> - 2012-11-04 19:08:37
|
Revision: 8558 http://sourceforge.net/p/oorexx/code-0/8558 Author: miesfeld Date: 2012-11-04 19:08:34 +0000 (Sun, 04 Nov 2012) Log Message: ----------- ooDialog: #494 ooDialog - ListView begin / end label editing events could be improved. See ticket [Feature-requests:#494] Modified Paths: -------------- docs/trunk/oodialog/en-US/deprecated.xml docs/trunk/oodialog/en-US/eventNotification.xml docs/trunk/oodialog/en-US/listview.xml docs/trunk/oodialog/en-US/treeview.xml docs/trunk/oodialog/en-US/userdialog.xml Modified: docs/trunk/oodialog/en-US/deprecated.xml =================================================================== --- docs/trunk/oodialog/en-US/deprecated.xml 2012-11-04 16:40:23 UTC (rev 8557) +++ docs/trunk/oodialog/en-US/deprecated.xml 2012-11-04 19:08:34 UTC (rev 8558) @@ -780,14 +780,20 @@ <section><title>removeSmallImages</title> <para> - This method is deprecated. It is replaced by the functionally equivalent <xref linkend="mthSetImageListClsListView"/> + This method is deprecated. It is replaced by the functionally equivalent <xref linkend="mthSetImageListClsListView"/> method. Do not use this method in new code. Try to migrate existing code to to the <computeroutput>setImageList()</computeroutput> method. This method may not exist in future versions of ooDialog. </para> </section> +<section><title>restoreEditClass</title> +<para> + This method is deprecated. It is not needed and was for internal use only. Invoking the method is currently a NOP. This + method may not exist in future versions of ooDialog. +</para> </section> + <section><title>setImages</title> <para> - This method is deprecated. It is replaced by the functionally equivalent <xref linkend="mthSetImageListClsListView"/> + This method is deprecated. It is replaced by the functionally equivalent <xref linkend="mthSetImageListClsListView"/> method. Do not use this method in new code. Try to migrate existing code to to the <computeroutput>setImageList()</computeroutput> method. This method may not exist in future versions of ooDialog. </para> </section> @@ -799,8 +805,14 @@ <computeroutput>setImageList()</computeroutput> method. This method may not exist in future versions of ooDialog. </para> </section> -</section> <!-- End Deprecated TreeView Methods Section --> +<section><title>subclassEdit</title> +<para> + This method is deprecated. It is not needed and was for internal use only. Invoking the method is currently a NOP. This + method may not exist in future versions of ooDialog. +</para> </section> +</section> <!-- End Deprecated ListView Methods Section --> + <section id="deprecatedProgressBar"><title>Deprecated ProgressBar Methods</title> <indexterm><primary>Deprecated</primary><secondary>progress bar methods</secondary></indexterm> @@ -881,6 +893,12 @@ <computeroutput>setImageList()</computeroutput> method. This method may not exist in future versions of ooDialog. </para> </section> +<section><title>restoreEditClass</title> +<para> + This method is deprecated. It is not needed and was for internal use only. Invoking the method is currently a NOP. This + method may not exist in future versions of ooDialog. +</para> </section> + <section><title>setImages</title> <para> This method is deprecated. It is replaced by the functionally equivalent <xref linkend="mthSetImageListClsTreeView"/> @@ -888,6 +906,12 @@ <computeroutput>setImageList()</computeroutput> method. This method may not exist in future versions of ooDialog. </para> </section> +<section><title>subclassEdit</title> |
From: <mie...@us...> - 2012-11-08 00:42:03
|
Revision: 8573 http://sourceforge.net/p/oorexx/code-0/8573 Author: miesfeld Date: 2012-11-08 00:41:59 +0000 (Thu, 08 Nov 2012) Log Message: ----------- #493 ooDialog - TreeView begin / end label editing could be improved See ticket [Feature-Requests:#493] Modified Paths: -------------- docs/trunk/oodialog/en-US/baseClasses.xml docs/trunk/oodialog/en-US/eventNotification.xml docs/trunk/oodialog/en-US/listview.xml docs/trunk/oodialog/en-US/menus.xml docs/trunk/oodialog/en-US/mouse.xml docs/trunk/oodialog/en-US/overview.xml docs/trunk/oodialog/en-US/treeview.xml docs/trunk/oodialog/en-US/userdialog.xml Modified: docs/trunk/oodialog/en-US/baseClasses.xml =================================================================== --- docs/trunk/oodialog/en-US/baseClasses.xml 2012-11-08 00:36:38 UTC (rev 8572) +++ docs/trunk/oodialog/en-US/baseClasses.xml 2012-11-08 00:41:59 UTC (rev 8573) @@ -4403,7 +4403,7 @@ </para> <para> The event handling method for the custom draw event will recieve a single object as its argument. The object - conveys information to the event handler concerning the event and recieves information from the event handle to pass + conveys information to the event handler concerning the event and receives information from the event handle to pass back to the underlying Windows control. The exact object will depend on the type of dialog control. List-views will receive a <link linkend="clsLvCustomDrawSimple">LvCustomDrawSimple</link> object and tree-views will receive a <link linkend="clsTvCustomDrawSimple">TvCustomDrawSimple</link> object. Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-08 00:36:38 UTC (rev 8572) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-08 00:41:59 UTC (rev 8573) @@ -89,7 +89,12 @@ events, the connection needs to be made explicitly. Indeed, except for trivial dialogs, most of the programming is deciding which events to be notified of and taking action upon receiving the notification. </para> -<para id="paraGuidelinesWhereToConnect" xreflabel="guidelines on where to"> + +<section id="sctConnectingEventHandlers"><title>Connecting Event Handlers</title> +<indexterm><primary>connecting event handlers</primary></indexterm> +<indexterm><primary>dialog object</primary><secondary>connecting event handlers</secondary></indexterm> +<indexterm><primary>EventNotification</primary><secondary>connecting event handlers</secondary></indexterm> +<para> In general, events should be connected before the dialog is shown on the screen, or immediately after the dialog is created. There is no reason why the programmer can not place the invocation where ever it makes the most sense. Connecting the events in the <xref linkend="mthInitDialog"/>() method is usually sufficient. In a @@ -99,6 +104,7 @@ the connect event method until <emphasis role="bold">after</emphasis> the <xref linkend="mthNewDialogObject"/> has been initialized. </para> +</section> <section id="sctCodingEventHandlers"><title>Coding Event Handlers</title> <indexterm><primary>coding event handlers</primary></indexterm> @@ -1061,10 +1067,8 @@ the window is gaining or losing the activation. </para> <para> - Common <xref linkend="paraGuidelinesWhereToConnect"/> invoke the <emphasis - role="italic">connectActivate</emphasis> method and on <link linkend="sctCodingEventHandlers">how</link> to code event - handlers are included in the documentation for the - <xref linkend="clsEventNotification"/> class. + 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 interpreter invokes the event handler directly and waits in the window <xref linkend="ovvWindowMessages"/> processing @@ -1428,10 +1432,8 @@ <orderedlist> <listitem> <para> - Common <xref linkend="paraGuidelinesWhereToConnect"/> invoke the <emphasis - role="italic">connectComboBoxEvent</emphasis> method and on <link linkend="sctCodingEventHandlers">how</link> - to code event handlers are included in the documentation for the - <xref linkend="clsEventNotification"/> class. + 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> <listitem> @@ -1612,10 +1614,8 @@ <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Common <xref linkend="paraGuidelinesWhereToConnect"/> invoke the <emphasis - role="italic">connectComboBoxEvent</emphasis> method and on <link linkend="sctCodingEventHandlers">how</link> - to code event handlers are included in the documentation for the - <xref linkend="clsEventNotification"/> class. + 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 methods receive two arguments: the first is a combination of the ID of the combo box and the ID of @@ -1948,10 +1948,8 @@ <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Common <xref linkend="paraGuidelinesWhereToConnect"/> invoke the <emphasis - role="italic">connectDateTimePickerEvent</emphasis> method and on <link linkend="sctCodingEventHandlers">how</link> - to code event handlers are included in the documentation for the - <xref linkend="clsEventNotification"/> class. + 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> @@ -3188,8 +3186,8 @@ <orderedlist> <listitem> <para> - There are some common <xref linkend="paraGuidelinesWhereToConnect"/> place the invocation of the event connection - methods. + 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> <listitem> @@ -4050,10 +4048,8 @@ <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Common <xref linkend="paraGuidelinesWhereToConnect"/> invoke the <emphasis - role="italic">connectListBoxEvent</emphasis> method and on <link linkend="sctCodingEventHandlers">how</link> - to code event handlers are included in the documentation for the - <xref linkend="clsEventNotification"/> class. + 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 methods receive two arguments: the first is a combination of the ID of the listbox and the ID of @@ -4164,7 +4160,7 @@ implement a drag-and-drop handler. </para> </listitem></varlistentry> - <varlistentry><term>BEGINEDIT</term> + <varlistentry id="kywListViewBEGINEDIT" 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 @@ -4186,12 +4182,12 @@ handler. </para> </listitem></varlistentry> - <varlistentry id="evtListViewDEFAULTEDIT" xreflabel="DEFAULTEDIT"><term>DEFAULTEDIT</term> + <varlistentry id="kywListViewDEFAULTEDIT" xreflabel="DEFAULTEDIT"><term>DEFAULTEDIT</term> <listitem> <para> This keyword is used to activate the internal handling of the list-view label editing operation. With this keyword, the ooDialog framework internally handles the BEGINEDIT and ENDEDIT notifications. The list-view must have the <xref - linkend="styListViewEDIT"/> style for the BEGINEDIT / ENDEIDT notification to be sent. While using the DEFAULTEDIT + linkend="styListViewEDIT"/> style for the BEGINEDIT / ENDEDIT notification to be sent. While using the DEFAULTEDIT connection may seem easier than using the BEGINEDIT / ENDEDIT connections, it does not provide the same flexibility as using the BEGINEDIT / ENDEDIT connections. </para> @@ -4217,7 +4213,7 @@ <listitem> <para> The check box state of an item changed. (The check box was checked or unchecked.) This event can only occur if - the list-view has the check box <xref linkend="mthAddExtendedStyle"/> list-view style. Use this + the list-view has the check box <link linkend="mthAddExtendedStyle">extended</link> list-view style. Use this keyword instead of the CHANGED keyword. </para> </listitem></varlistentry> @@ -4255,7 +4251,7 @@ All items have been deleted. </para> </listitem></varlistentry> - <varlistentry><term>ENDEDIT</term> + <varlistentry id="kywListViewENDEDIT" xreflabel="ENDEDIT"><term>ENDEDIT</term> <listitem> <para> Label editing has ended. Do not connect this event if you are using the DEFAULTEDIT keyword. The results are @@ -4276,7 +4272,7 @@ CHANGED keyword. </para> </listitem></varlistentry> - <varlistentry id='kywListViewGETINFOTIP'><term>GETINFOTIP</term> + <varlistentry id="kywListViewGETINFOTIP" xreflabel="GETINFOTIP"><term>GETINFOTIP</term> <listitem> <para> The list-view control is requesting text to display an info tip. The notification is only sent when the list-view @@ -4512,7 +4508,7 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The event handling method recieves 4 arguments: + The event handling method receives 4 arguments: </para> <variablelist> <varlistentry><term>id</term> @@ -4563,9 +4559,9 @@ <listitem> <para> The following example shows a possible event handler for the BEGINEDIT event. It uses the <emphasis - role="italic">itemIndex</emphasis> argument to determine which it is about the have its label edited, and checks that - editing is allowed for that item. If it is, it returns true to allow the operation. If it is not, it returns false to - cancel the operation and puts up a message box to inform the user: + role="italic">itemIndex</emphasis> argument to determine which item is about the have its label edited, and checks + that editing is allowed for that item. If it is, it returns true to allow the operation. If it is not, it returns + false to cancel the operation and puts up a message box to inform the user: <programlisting> <![CDATA[ @@ -4609,7 +4605,7 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The event handling method recieves 2 arguments: + The event handling method receives 2 arguments: </para> <variablelist> <varlistentry><term>id</term> @@ -4833,7 +4829,7 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The event handling method recieves 4 arguments: + The event handling method receives 4 arguments: </para> <variablelist> <varlistentry><term>id</term> @@ -4929,7 +4925,7 @@ <programlisting> <![CDATA[ - ::method onBeginEdit unguarded + ::method onEndEdit unguarded use arg id, itemIndex, maybeText ]]> </programlisting> @@ -4938,7 +4934,7 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The event handling method recieves 3 arguments: + The event handling method receives 3 arguments: </para> <variablelist> <varlistentry><term>id</term> @@ -4950,7 +4946,7 @@ <varlistentry><term>itemIndex</term> <listitem> <para> - This index of the list-view item that was edited. + The index of the list-view item that was edited. </para> </listitem></varlistentry> <varlistentry><term>text [optional]</term> @@ -5005,7 +5001,7 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The event handling method recieves 4 arguments: + The event handling method receives 4 arguments: </para> <variablelist> <varlistentry><term>id</term> @@ -5544,10 +5540,8 @@ <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Common <xref linkend="paraGuidelinesWhereToConnect"/> invoke the <emphasis - role="italic">connectMonthCalendarEvent</emphasis> method and on <link linkend="sctCodingEventHandlers">how</link> - to code event handlers are included in the documentation for the - <xref linkend="clsEventNotification"/> class. + 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> @@ -6489,10 +6483,8 @@ of the dialog being resized and, if desired, can change its size or position. </para> <para> - Common <xref linkend="paraGuidelinesWhereToConnect"/> invoke the <emphasis - role="italic">connectResizing</emphasis> method and on <link linkend="sctCodingEventHandlers">how</link> - to code event handlers are included in the documentation for the - <xref linkend="clsEventNotification"/> class. + 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 interpreter invokes the event handler directly and waits in the window <xref linkend="ovvWindowMessages"/> processing @@ -7161,8 +7153,8 @@ <orderedlist> <listitem> <para> - There are some common <xref linkend="paraGuidelinesWhereToConnect"/> place the invocation of the event - connection methods. + 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> <listitem> @@ -7327,10 +7319,8 @@ <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Common <xref linkend="paraGuidelinesWhereToConnect"/> invoke the <emphasis - role="italic">connectTabEvent</emphasis> method and on <link linkend="sctCodingEventHandlers">how</link> - to code event handlers are included in the documentation for the - <xref linkend="clsEventNotification"/> class. + 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 KEYDOWN event receives two arguments: info about the event, the control ID of the @@ -7519,10 +7509,8 @@ <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Common <xref linkend="paraGuidelinesWhereToConnect"/> invoke the <emphasis - role="italic">connectUpDownEvent</emphasis> method and on <link linkend="sctCodingEventHandlers">how</link> to - code event handlers are included in the documentation for the - <xref linkend="clsEventNotification"/> class. + 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> @@ -7808,13 +7796,10 @@ <member>BEGINEDIT</member> <member>BEGINRDRAG</member> <member>DEFAULTEDIT</member> - <member>CHECKBOXCHANGED</member> - <member>CLICK</member> - <member>COLUMNCLICK</member> <member>DELETE</member> <member>ENDEDIT</member> + <member>EXPANDED</member> <member>EXPANDING</member> - <member>EXPANDED</member> <member>GETINFOTIP</member> <member>KEYDOWN</member> <member>KEYDOWNEX</member> @@ -7831,11 +7816,19 @@ implement a drag-and-drop handler. </para> </listitem></varlistentry> - <varlistentry><term>BEGINEDIT</term> + <varlistentry id="kywTreeViewBEGINGEDIT" xreflabel="BEGINEDIT"><term>BEGINEDIT</term> <listitem> <para> - Editing a label has been started. + Editing a label has been started. Do not connect this event if you are using the DEFAULTEDIT keyword. The results are + undefined. The tree-view must have the <xref linkend="styTreeViewEDIT"/> style for this notification to be sent. </para> + <para> + The event notification for this event has been enhanced since the original ooDialog implementation. To use the + enhanced event notification, the <emphasis role="italic">willReply</emphasis> argument must be used. The value of the + argument, true or false, does not matter. If <emphasis role="italic">willReply</emphasis> is omitted, the old style + notification is used. The documentation for the <link linkend="evtTreeViewBEGINEDIT">BEGINEDIT</link> event handler + explains the difference between the two types of notifications. + </para> </listitem></varlistentry> <varlistentry><term>BEGINRDRAG</term> <listitem> @@ -7845,35 +7838,40 @@ implement a drag-and-drop handler. handler. </para> </listitem></varlistentry> - <varlistentry id="evtTreeViewDEFAULTEDIT"><term>DEFAULTEDIT</term> + <varlistentry id="kywTreeViewDEFAULTEDIT" xreflabel="DEFAULTEDIT"><term>DEFAULTEDIT</term> <listitem> <para> - This event connects the notification that label editing has been started and ended with a predefined event-handling - method. This method extracts the newly entered text from the notification and modifies the item of which the label - was edited. If this event is not connected you must provide your own event-handling method and connect it with the - BEGINEDIT and ENDEDIT events. Otherwise, the edited text is lost and the item remains unchanged. + This keyword is used to activate the internal handling of the tree-view label editing operation. With this keyword, + the ooDialog framework internally handles the BEGINEDIT and ENDEDIT notifications. The tree-view must have the + <xref linkend="styTreeViewEDIT"/> style for the BEGINEDIT / ENDEDIT notification to be sent. While using the + DEFAULTEDIT connection may seem easier than using the BEGINEDIT / ENDEDIT connections, it does not provide the same + flexibility as using the BEGINEDIT / ENDEDIT connections. </para> <para> - When you specify this event, the <emphasis role="italic">msgToRaise</emphasis> argument is ignored. + When you specify this event connection, omit the <emphasis role="italic">methodName</emphasis> argument, the arugment + is ignored. Do not connect either the BEGINEDIT or ENDEDIT events when also using the DEFAULTEDIT connection. The + result is undefined. </para> </listitem></varlistentry> - <varlistentry id="evtTreeViewENDEDIT"><term>ENDEDIT</term> - <listitem> - <para> - Label editing has ended. - </para> - </listitem></varlistentry> <varlistentry><term>DELETE</term> <listitem> <para> An item has been deleted. </para> </listitem></varlistentry> - <varlistentry><term>EXPANDING</term> + <varlistentry id="kywTreeViewENDEDIT" xreflabel="ENDEDIT"><term>ENDEDIT</term> <listitem> <para> - An item is about to expand or collapse. This notification is sent before the item has expanded or collapsed. + Label editing has ended. Do not connect this event if you are using the DEFAULTEDIT keyword. The results are + undefined. The tree-view must have the <xref linkend="styTreeViewEDIT"/> style for this notification to be sent. </para> + <para> + The event notification for this event has been enhanced since the original ooDialog implementation. To use the + enhanced event notification, the <emphasis role="italic">willReply</emphasis> argument must be used. The value of the + argument, true or false, does not matter. If <emphasis role="italic">willReply</emphasis> is omitted, the old style + notification is used. The documentation for the <link linkend="evtTreeViewENDEDIT">ENDEDIT</link> event handler + explains the difference between the two types of notifications. + </para> </listitem></varlistentry> <varlistentry><term>EXPANDED</term> <listitem> @@ -7881,9 +7879,15 @@ An item has expanded or collapsed. This notification is sent after the item expanded or collapsed. </para> </listitem></varlistentry> - <varlistentry id="kywTreeViewGETINFOTIP"><term>GETINFOTIP</term> + <varlistentry><term>EXPANDING</term> <listitem> <para> + An item is about to expand or collapse. This notification is sent before the item has expanded or collapsed. + </para> + </listitem></varlistentry> + <varlistentry id="kywTreeViewGETINFOTIP" xreflabel="GETINFOTIP"><term>GETINFOTIP</term> + <listitem> + <para> The tree-view control is requesting text to display an info tip. The notification is only sent when the tree-view control has the <link linkend="styTreeViewInfoTip">INFOTIP</link> style. </para> @@ -7940,9 +7944,9 @@ </para> <para> <emphasis role="bold">Note:</emphasis> Currently the <emphasis role="italic">willReply</emphasis> argument is ignored - for all events except the EXPANDING, EXPANDED, and KEYDOWNEX events. For the GETINFOTIP event, the interpreter always - waits for the reply. For all other events, the interpreter never waits for the reply from the event handler. Future - enhancements to the <computeroutput>TreeView</computeroutput> class may allow the <emphasis + for all events except the BEGINEDIT, ENDEDIT, EXPANDING, EXPANDED, and KEYDOWNEX events. For the GETINFOTIP event, the + interpreter always waits for the reply. For all other events, the interpreter never waits for the reply from the event + handler. Future enhancements to the <computeroutput>TreeView</computeroutput> class may allow the <emphasis role="italic">willReply</emphasis> to have effect for all tree-view event notifications. </para> </listitem></varlistentry> @@ -7977,200 +7981,700 @@ <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Common <xref linkend="paraGuidelinesWhereToConnect"/> invoke the <emphasis - role="italic">connectTreeViewEvent</emphasis> method and on <link linkend="sctCodingEventHandlers">how</link> - to code event handlers are included in the documentation for the - <xref linkend="clsEventNotification"/> class. + See the sections on <link linkend="sctConnectingEventHandlers">connecting</link> and <link + linkend="sctCodingEventHandlers">coding</link> event handlers for additional information on event handlers. </para> - <orderedlist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details:</emphasis></term> <listitem> <para> - The event-handling method connected to ENDEDIT receives two arguments: the item handle of which the label has been - edited and the newly entered text. Example: + 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 + command events happen. + </para> + <para> + In Windows itself, tree view event notifications are sent to the parent dialog using the WM_NOTIFY message. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + The following example connects the selection-changed event for the tree-view with the symbolic ID of IDC_TV_FILES with + the method newTreeSelection in the Rexx dialog. The event handling method displays the text of the new selection: + <programlisting> + <![CDATA[ + ::class 'FileDlg' subclass UserDialog + ::method init + self~connectTreeViewEvent(IDC_TV_FILES, "SELCHANGED", "newTreeSelection") + + ::method newTreeSelection unguarded + tc = self~newTreeView(IDC_TV_FILES) + text = tc~itemText(tc~selected) + say "The label of the new selection is:" text + + return 0 + ]]> + </programlisting> + </para> + </listitem></varlistentry> +</variablelist> + +<section id="evtTreeViewBEGINDRAG" xreflabel="BEGINDRAG"><title>BeginDrag Event Handler</title> +<indexterm><primary>TreeView Event</primary><secondary>BEGINDRAG</secondary></indexterm> + +<para> + The event-handling method connected to BEGINDRAG receives three arguments: the control ID of the tree view control, the + tree item to be dragged, and the point where the mouse cursor was pressed (x and y positions, separated by a blank). + Example: + <programlisting> <![CDATA[ -::method onEndEdit unguarded - use arg item, newText +::method onBeginDrag unguarded + use arg id, item, where + say "Item with handle" item "is in drag-and-drop mode" + parse var where x y + say "The drag operation started at point ("x","y")" return 0 ]]> </programlisting> - </para> - </listitem> - <listitem> - <para> - The event-handling method connected to KEYDOWN receives two arguments: the control ID of the tree view control and the - virtual key code pressed. Use the <xref linkend="mthKey2Name"/>method of the - <xref linkend="clsVK"/> class to determine which key was pressed. Example: +</para> +</section> +<section id="evtTreeViewBEGINRDRAG" xreflabel="BEGINRDRAG"><title>BeginRDrag Event Handler</title> +<indexterm><primary>TreeView Event</primary><secondary>BEGINRDRAG</secondary></indexterm> + +<para> + The event-handling method connected to BEGINRDRAG receives three arguments: the control ID of the tree view control, the + tree item to be dragged, and the point where the mouse cursor was pressed (x and y positions, separated by a blank). + Example: + <programlisting> <![CDATA[ -::method onKeyDown unguarded - use arg id, vkey - say "Key" .VK~name2key(vkey) "was pressed." +::method onBeginDrag unguarded + use arg id, item, where + say "Item with handle" item "is in drag-and-drop mode" + parse var where x y + say "The drag operation started at point ("x","y")" return 0 ]]> </programlisting> - </para> - </listitem> +</para> +</section> + + +<section id="evtTreeViewBEGINEDIT" xreflabel="BEGINEDIT"><title>BeginEdit Event Handler</title> +<indexterm><primary>TreeView Event</primary><secondary>BEGINEDIT</secondary></indexterm> +<para> + The event handler for the BEGINEDIT event is invoked when the user begins a label editing operation on an item of the + tree-view. When label editing begins, an edit control is created by the operating systm, but not positioned or displayed. + Before it is displayed, the tree-view control sends a BEGINEDIT notification message. A label editing operation is only + available when the tree-view has the <xref linkend="styTreeViewEDIT"/> style. +</para> +<para> + In general, the programmer would connect both the BEGINEDIT and <xref linkend="kywTreeViewENDEDIT"/> 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="mthConnectTreeViewEvent"/> 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> + +<variablelist> + <varlistentry><term><emphasis role="bold">New event handler description:</emphasis></term> <listitem> - <para> - The event-handling method connected to the EXPANDED event receives four arguments: the control ID of the tree view - control, the handle of the tree item that expanded or collapsed, a string that indicates whether the item was expanded or - collapsed, and a string with possible extra information.. Recall that the EXPANDED notification is sent <emphasis - role="italic">after</emphasis> the item has been expanded or collapsed. - </para> - <para> - The <emphasis role="italic">what</emphasis> argument will be either <emphasis role="italic">EXPANDED</emphasis> or - <emphasis role="italic">COLLAPSED</emphasis>. The <emphasis role="italic">extra</emphasis> arugment will usually be the - empty string. The Microsoft documentation seems to indicate that when an item is expanded, the action may be expanded - partial and when the action is collapsed, it may be collapsed and reset. If expanded partial is detected, the <emphasis - role="italic">extra</emphasis> argument will be <emphasis role="italic">PARTIAL</emphasis>. If collapse and reset is - detected, the <emphasis role="italic">extra</emphasis> argument will be <emphasis role="italic">RESET</emphasis>. - However, in testing, neither of these 2 actions were every detected and the Microsoft documentation is unclear here. It - may be that the <emphasis role="italic">extra</emphasis> argument will always be the empty string. - </para> - <para> - If the <emphasis role="italic">willReply</emphasis> argument to <emphasis role="italic">connectTreeViewEvent</emphasis> - is true, the interpreter will wait for the reply from the event handler. However Windows ignores the reply, so returning - any value is sufficient. - </para> - <para> - Example: + <para> + Whether the programmer must return a value and if the interpreter waits, or does not wait, for this return is + determined by the value of the <emphasis role="italic">willReply</emphasis> argument. If <emphasis + role="italic">willReply</emphasis> is true, the programmer must return true or false from the event handler and the + interpreter waits for that reply. If <emphasis role="italic">willReply</emphasis> is false the interpreter does not + wait for a reply. + </para> - <programlisting> - <![CDATA[ - ::method onExpanded unguarded - use arg id, item, what, extra - say "The item with handle" item "has been" what + <programlisting> + <![CDATA[ + ::method onBeginEdit unguarded + use arg id, hItem, editCtrl, treeViewCtrl, userData - return 0 + return zz + ]]> + </programlisting> - /* - Possible output: + <variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method receives 4 arguments: + </para> + <variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The resource id of the list-view sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>hItem</term> + <listitem> + <para> + The tree-view item handle whose label is about to be edited. + </para> + </listitem></varlistentry> + <varlistentry><term>editCtrl</term> + <listitem> + <para> + The Rexx edit control object used for the editing operation. The programmer can customize the editing operation by + using the methods of the <link linkend="clsEdit">Edit</link> class. + </para> + <para> + <emphasis role="bold">Note</emphasis> that this object is only valid during the editing operation. When the user + ends the editing, the operating system destroys the underlying edit control and the Rexx object is no longer valid. + Each time the user starts a new editing operation, the operating system creates a new edit control. + </para> + </listitem></varlistentry> + <varlistentry><term>treeViewCtrl</term> + <listitem> + <para> + The Rexx tree-view object whose underlying tree-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="mthNewTreeView"/> method. Unlike the <emphasis role="italic">editCtrl</emphasis> object, this object is + valid as long as the dialog is executing. + </para> + </listitem></varlistentry> + <varlistentry><term>userData</term> + <listitem> + <para> + The user <link linkend="mthSetItemDataClsTreeView">data</link> object assigned to the tree-view item whose label is + about to be edited. If no user data has been assigned, this argument will be the + <computeroutput>.nil</computeroutput> object. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + When the programmer used true for the <emphasis role="italic">willReply</emphasis> argument, the event handler must + return true or false. To allow the editing operation to begin, return true. To cancel the editing operation, return + false. Returning a value from the event handler gives the programmer the option determining if the label for the + specific tree-view item should or should not be edited. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example</emphasis></term> + <listitem> + <para> + The following example shows a possible event handler for the BEGINEDIT event. It uses the <emphasis + role="italic">hItem</emphasis> argument to determine which item is about the have its label edited, and checks that + editing is allowed for that item. If it is, it returns true to allow the operation. If it is not, it returns false to + cancel the operation and puts up a message box to inform the user. Note that the <emphasis + role="italic">userData</emphasis> argument is assigned to the <emphasis role="italic">rec</emphasis> variable in this + example, just to make it clear that the argument sent to the event handler is the user data object. In this + particular program the user data object is a record object: - The item with handle 0x00000000001AD3E0 has been COLLAPSED - */ - ]]> - </programlisting> +<programlisting> +<![CDATA[ - </para> - </listitem> +::method onBeginEdit unguarded + use arg id, hItem, editCtrl, treeViewCtrl, userData + + rec = userData + if rec~isEditable then return .true + + reply .false + + msg = "The record for" rec~FirstName rec~LastName 'can not be changed.' + title = "Label Edit Error" + j = MessageDialog(msg, self~hwnd, title, , "WARNING") + + return + +]]> +</programlisting> + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Old event handler description:</emphasis></term> <listitem> <para> - The event-handling method connected to the EXPANDING event receives four arguments: the control ID of the tree view - control, the handle of the tree item that is about to be expanded or collapsed, a string that indicates whether the item - will be expanded or collapsed, and a string with possible extra information.. Recall that the EXPANDING notification is - sent <emphasis role="italic">before</emphasis> the item is expanded or collapsed. + The old style event notification is used when the programmer omits the <emphasis role="italic">willReply</emphasis> + argument in the invocation of the <xref linkend="mthConnectListViewEvent"/> method. The return from the event handler is + completely ignored, the interpreter does not wait for this return. </para> - <para> - The <emphasis role="italic">what</emphasis> argument will be either <emphasis role="italic">EXPANDED</emphasis> or - <emphasis role="italic">COLLAPSED</emphasis>. The <emphasis role="italic">extra</emphasis> arugment will usually be the - empty string. The Microsoft documentation seems to indicate that when an item is about to be expanded, the action may be - expanded partial and when the action is about to be collapsed, it may be collapsed and reset. If expanded partial is - detected, the <emphasis role="italic">extra</emphasis> argument will be <emphasis role="italic">PARTIAL</emphasis>. If - collapse and reset is detected, the <emphasis role="italic">extra</emphasis> argument will be <emphasis - role="italic">RESET</emphasis>. However, in testing, neither of these 2 actions were every detected and the Microsoft - documentation is unclear here. It may be that the <emphasis role="italic">extra</emphasis> argument will always be the - empty string. - </para> - <para> - If the <emphasis role="italic">willReply</emphasis> argument to <emphasis role="italic">connectTreeViewEvent</emphasis> - is true, the interpreter will wait for the reply from the event handler. The programmer <emphasis - role="italic">must</emphasis> return either true or false. The programmer can prevent the expansion or collapse for the - item by returning false. To allow the expansion or collapse to take place, the programmer must return true. - </para> - <para> - Example: <programlisting> <![CDATA[ - ::method onExpanding unguarded - use arg id, item, what - say "Item with handle" item "is going to be" what + ::method onBeginEdit unguarded + use arg id, hItem + ]]> + </programlisting> - return .true + <variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method receives 2 arguments: + </para> + <variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The resource id of the list-view sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>hItem</term> + <listitem> + <para> + The handle to the tree-view item whose label is about to be edited. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + Returning, or not returning, a value has no meaning. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks</emphasis></term> + <listitem> + <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> +</variablelist> - /* - Possible output: +</section> <!-- End BeginEdit Event Handler --> - The item with handle 0x00000000001AD680 has been EXPANDED - */ - ]]> - </programlisting> +<section id="evtTreeViewENDEDIT" xreflabel="ENDEDIT"><title>EndEdit Event Handler</title> +<indexterm><primary>TreeView Event</primary><secondary>ENDEDIT</secondary></indexterm> +<para> + The event handler for the ENDEDIT event is invoked when the user finishes a label editing operation on an item of the + tree-view. A label editing operation is only available when the tree-view has the <xref linkend="styTreeViewEDIT"/> style. +</para> +<para> + In general, the programmer would connect both the <xref linkend="evtTreeViewBEGINEDIT"/> 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="mthConnectTreeViewEvent"/> 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> - </para> - </listitem> +<variablelist> + <varlistentry><term><emphasis role="bold">New event handler description:</emphasis></term> <listitem> + <para> + Whether the programmer must return a value and if the interpreter waits, or does not wait, for this return is + determined by the value of the <emphasis role="italic">willReply</emphasis> argument. If <emphasis + role="italic">willReply</emphasis> is true, the programmer must return true or false from the event handler and the + interpreter waits for that reply. If <emphasis role="italic">willReply</emphasis> is false the interpreter does not + wait for a reply. + </para> + + <programlisting> + <![CDATA[ + ::method onEndEdit unguarded + use arg id, hItem, text, treeViewCtrl, userData + + return trueOrFalse + ]]> + </programlisting> + + <variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method receives 4 arguments: + </para> + <variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The resource id of the list-view sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>itemID</term> + <listitem> + <para> + The item index whose label being edited. + </para> + </listitem></varlistentry> + <varlistentry><term>text</term> + <listitem> + <para> + If the user canceled the edit operation then the <emphasis role="italic">text</emphasis> argument will be the .nil + object. If the edit operation was not canceled then this argument will be the text the user entered. + </para> + </listitem></varlistentry> + <varlistentry><term>listViewCtrl</term> + <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="mthNewListView"/> method. + </para> + </listitem></varlistentry> + <varlistentry><term>userData</term> + <listitem> + <para> + The user <link linkend="mthSetItemDataClsTreeView">data</link> object assigned to the tree-view item whose label + was edited. If no user data has been assigned, this argument will be the <computeroutput>.nil</computeroutput> + object. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + When the programmer used true for the <emphasis role="italic">willReply</emphasis> argument, the event handler must + return true or false. To accept the edited text, return true. To disallow the the change to the label, return false. + If, the edit operation was canceled by the user, the operating system ignores the return from the event handler. + Returning a value from the event handler gives the programmer the option of determining if the new label for the + specific tree-view item is acceptable. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example</emphasis></term> + <listitem> + <para> + The following example checks the new text entered by the user. The label for each tree-view item is a part number. + If the user's text is not a valid part number, the new text is rejected by returning false: + +<programlisting> +<![CDATA[ + +::method onEndEdit unguarded + use arg id, itemIndex, text, treeViewCtrl, userData + + if text == .nil then return .false + + if self~isValidPart(text) then do + reply .true + + rec = userData + oldPartNo = rec~partNo + rec~partNo = text + self~updateRecord(oldPartNo, rec) + + return + end + + reply .false + + msg = text "is not a valid part number." || .endOfLine~copies(2 || - + "The change is rejected." + + title = "Label Editing Error" + j = MessageDialog(msg, self~hwnd, title, , "WARNING") + + return + +]]> +</programlisting> + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Old event handler description:</emphasis></term> + <listitem> <para> - The event-handling method connected to BEGINDRAG or BEGINRDRAG receives three arguments: the control ID of the tree - view control, the tree item to be dragged, and the point where the mouse cursor was pressed (x and y positions, - separated by a blank). Example: + The old style event notification is used when the programmer omits the <emphasis role="italic">willReply</emphasis> + argument in the invocation of the <xref linkend="mthConnectTreeViewEvent"/> method. The return from the event handler is + completely ignored, the interpreter does not wait for this return. If the user canceled the edit operation, the label + will be unchanged. If the user did not cancel the edit operation, the label of the item is changed to the text the user + entered. + </para> <programlisting> <![CDATA[ - - ::method onBeginDrag unguarded - use arg id, item, where - say "Item with handle" item "is in drag-and-drop mode" - parse var where x y - say "The drag operation started at point ("x","y")" - - return 0 + ::method onEndEdit unguarded + use arg id, hItem, maybeText ]]> </programlisting> - </para> - </listitem> - </orderedlist> + <variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method receives 3 arguments: + </para> + <variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The resource id of the tree-view sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>hItem</term> + <listitem> + <para> + The handle of the tree-view item that was edited. + </para> + </listitem></varlistentry> + <varlistentry><term>text [optional]</term> + <listitem> + <para> + If the user canceled the edit operation, the <emphasis role="italic">text</emphasis> argument is omitted. If the user + did not cancel, then the <emphasis role="italic">text</emphasis> argument is the text the user entered. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + Returning, or not returning, a value has no meaning. The interpreter does not wait for the return and its value, if any + is discarded. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks</emphasis></term> + <listitem> + <para> + 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="mthConnectTreeViewEvent"/> method. + </para> + </listitem></varlistentry> + </variablelist> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details:</emphasis></term> +</variablelist> + +</section> <!-- End EndEdit Event Handler --> + + +<section id="evtTreeViewEXPANDED" xreflabel="EXPANDED"><title>Expanded Event Handler</title> +<indexterm><primary>TreeView Event</primary><secondary>EXPANDED</secondary></indexterm> +<para> + The event handler for the EXPANDED event is invoked when after a tree-view item has been expanded or collapsed. +</para> +<para> + If the <emphasis role="italic">willReply</emphasis> argument to <xref linkend="mthConnectTreeViewEvent"/> method + is true, the interpreter will wait for the reply from the event handler. However Windows ignores the reply, so returning + any value is sufficient. If <emphasis role="italic">willReply</emphasis> is false or omitted, the interpreter does not wait + for the reply. +</para> + +<programlisting> +<![CDATA[ +::method onExpanded unguarded + use arg id, hItem, what, extra + + return 0 +]]> +</programlisting> + +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> + <para> + The event handling method recieves 4 arguments: + </para> + <variablelist> + <varlistentry><term>id</term> + <listitem> <para> - The <emphasis role="italic">connectTreeViewEvent</emphasis> method is a member of the - <xref linkend="clsEventNotification"/> mixin class. + The resource ID of the tree-view control sending the notification. </para> + </listitem></varlistentry> + <varlistentry><term>hItem</term> + <listitem> + <para> + The handle of the tree-view item that expanded or collapsed. + </para> + </listitem></varlistentry> + <varlistentry><term>what</term> + <listitem> + <para> + A string that indicates whether the item was expanded or collapsed. The string will be either <emphasis + role="italic">EXPANDED</emphasis> or <emphasis role="italic">COLLAPSED</emphasis>. + </para> + </listitem></varlistentry> + <varlistentry><term>extra</term> + <listitem> + <para> + The <emphasis role="italic">extra</emphasis> arugment will usually be the empty string. The Microsoft documentation + seems to indicate that when an item is expanded, the action may be expanded partial and when the action is collapsed, + it may be collapsed and reset. If expanded partial is detected, the <emphasis role="italic">extra</emphasis> argument + will be <emphasis role="italic">PARTIAL</emphasis>. If collapse and reset is detected, the <emphasis + role="italic">extra</emphasis> argument will be <emphasis role="italic">RESET</emphasis>. However, in testing, neither + of these 2 actions were ever detected and the Microsoft documentation is unclear here. It may be that the <emphasis + role="italic">extra</emphasis> argument will always be the empty string. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> <para> - Syntax errors are raised when incorrect usage is detected. + Since the return from the event handler is ignored by the operating system, any value can be returned. 0 makes a good + return value. </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 - command events happen. + The following example displays the expanded or collapsed action that has just happened: + +<programlisting> +<![CDATA[ + +::method onExpanded unguarded + use arg id, item, what, extra + say "The item with handle" item "has been" what + + return 0 + +/* + Possible output: + + The item with handle 0x00000000001AD3E0 has been COLLAPSED +*/ + +]]> +</programlisting> </para> + </listitem></varlistentry> +</variablelist> + +</section> <!-- End Expanded Event Handler --> + + +<section id="evtTreeViewEXPANDING" xreflabel="EXPANDING"><title>Expanding Event Handler</title> +<indexterm><primary>TreeView Event</primary><secondary>EXPANDING</secondary></indexterm> +<para> + The event-handling method connected to the EXPANDING event receives four arguments: the control ID of the tree view + control, the handle of the tree item that is about to be expanded or collapsed, a string that indicates whether the item + will be expanded or collapsed, and a string with possible extra information.. Recall that the EXPANDING notification is + sent <emphasis role="italic">before</emphasis> the item is expanded or collapsed. +</para> +<para> + The <emphasis role="italic">what</emphasis> argument will be either <emphasis role="italic">EXPANDED</emphasis> or + <emphasis role="italic">COLLAPSED</emphasis>. The <emphasis role="italic">extra</emphasis> arugment will usually be the + empty string. The Microsoft documentation seems to indicate that when an item is about to be expanded, the action may be + expanded partial and when the action is about to be collapsed, it may be collapsed and reset. If expanded partial is + detected, the <emphasis role="italic">extra</emphasis> argument will be <emphasis role="italic">PARTIAL</emphasis>. If + collapse and reset is detected, the <emphasis role="italic">extra</emphasis> argument will be <emphasis + role="italic">RESET</emphasis>. However, in testing, neither of these 2 actions were every detected and the Microsoft + documentation is unclear here. It may be that the <emphasis role="italic">extra</emphasis> argument will always be the + empty string. +</para> +<para> + Example: + +<programlisting> +<![CDATA[ +]]> +</programlisting> + +</para> +<para> + The event handler for the EXPANDING event is invoked <emphasis role="italic">before</emphasis> a tree-view item is + going to be expanded or collapsed. +</para> +<para> + If the <emphasis role="italic">willReply</emphasis> argument to <xref linkend="mthConnectTreeViewEvent"/> method is true, + the interpreter will wait for the reply from the event handler. The programmer <emphasis role="italic">must</emphasis> + return either true or false. The programmer can prevent the expansion or collapse for the item by returning false. To allow + the expansion or collapse to take place, the programmer must return true. +</para> + +<programlisting> +<![CDATA[ +::method onExpanding unguarded + use arg id, hItem, what, extra + + return trueOrFalse +]]> +</programlisting> + +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> <para> - In Windows itself, tree view event notifications are sent to the parent dialog using the WM_NOTIFY message. + The event handling method recieves 4 arguments: </para> + <variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The resource ID of the tree-view control sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>hItem</term> + <listitem> + <para> + The handle of the tree-view item that is about to expand or collapse. + </para> + </listitem></varlistentry> + <varlistentry><term>what</term> + <listitem> + <para> + A string that indicates whether the item is going to expand or collapsd. The string will be either <emphasis + role="italic">EXPANDED</emphasis> or <emphasis role="italic">COLLAPSED</emphasis>. + </para> + </listitem></varlistentry> + <varlistentry><term>extra</term> + <listitem> + <para> + The <emphasis role="italic">extra</emphasis> arugment will usually be the empty string. The Microsoft documentation + seems to indicate that when an item is going to expand, the action may be expanded partial and when the action is + collapsed, it may be collapsed and reset. If expanded partial is detected, the <emphasis role="italic">extra</emphasis> + argument will be <emphasis role="italic">PARTIAL</emphasis>. If collapse and reset is detected, the <emphasis + role="italic">extra</emphasis> argument will be <emphasis role="italic">RESET</emphasis>. However, in testing, neither + of these 2 actions were ever detected and the Microsoft documentation is unclear here. It may be that the <emphasis + role="italic">extra</emphasis> argument will always be the empty string. + </para> + </listitem></varlistentry> + </variablelist> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> <listitem> <para> - The following example connects the selection-changed event for the tree view FileTree with method NewTreeSelection - and displays the text of the new selection: - <programlisting> - <![CDATA[ - ::class MyDlgClass subclass UserDialog + If the programmer used the <emphasis role="italic">willReply</emphasis> argument with a true value, the event handler + must return true or false. Returning true, allows the expansion or collapse to happen. Returning false prevents the + expansion or collapse. If the <emphasis role="italic">willReply</emphasis> argument was false or omitted, the interpreter + does not wait for the reply. The event handler can return any value, or not return a value at all. Good practice would be + to always return a value from an event handler. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example</emphasis></term> + <listitem> + <para> + The following example allows the expansion or collapse to continue and simply prints out what is about to happen: - ::method init - self~connectTreeViewEvent(IDC_TV_FILES, "SELCHANGED", "newTreeSelection") +<programlisting> +<![CDATA[ - ::method newTreeSelection unguarded - tc = self~newTreeView(IDC_TV_FILES) - info. = tc~itemInfo(tc~selected) - say "New selection is:" info.!text +::method onExpanding unguarded + use arg id, item, what, extra + say "Item with handle" item "is going to be" what - return 0 - ]]> - </programlisting> + return .true + + /* + Possible output: + + Item with handle 0x00000000001AD680 is going to be EXPANDED + */ + +]]> +</programlisting> </para> </listitem></varlistentry> </variablelist> +</section> <!-- End Expanding Event Handler --> + + <section id="evtTreeViewGETINFOTIP"><title>GetInfoTip Event Handler</title> <indexterm><primary>TreeView Event</primary><secondary>GETINFOTIP</secondary></indexterm> <para> @@ -8193,7 +8697,7 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The event handling method recieves 5 arguments: + The event handling method receives 5 arguments: </para> <variablelist> <varlistentry><term>id</term> @@ -8268,6 +8772,85 @@ </section> <!-- End GetInfoTip Event Handler --> +<section id="evtTreeViewKEYDOWN" xreflabel="KEYDOWN"><title>KeyDown Event Handler</title> +<indexterm><primary>TreeView Event</primary><secondary>KEYDOWN</secondary></indexterm> +<para> + The event handler for the key down event is invoked when the user types a key within the tree-view control. The event + handler is similar to the event handler for the <link linkend="evtTreeViewKEYDOWNEX">KEYDOWNEX</link> event, it is invoked + for the same event. However, when the KEYDOWN keyword is use, the event ... [truncated message content] |
From: <mie...@us...> - 2012-11-08 04:15:36
|
Revision: 8576 http://sourceforge.net/p/oorexx/code-0/8576 Author: miesfeld Date: 2012-11-08 04:15:32 +0000 (Thu, 08 Nov 2012) Log Message: ----------- ooDialog doc - incremental update Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml docs/trunk/oodialog/en-US/listview.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-08 03:21:51 UTC (rev 8575) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-08 04:15:32 UTC (rev 8576) @@ -101,8 +101,8 @@ <computeroutput>UserDialog</computeroutput>, the <xref linkend="mthDefineDialog"/>() method also makes a good place for the connect event methods. If the programmer is overriding the <emphasis role="italic">init</emphasis>() method, the connect event methods can be placed there. In this case, do not invoke - the connect event method until <emphasis role="bold">after</emphasis> the - <xref linkend="mthNewDialogObject"/> has been initialized. + the connect event method until <emphasis role="bold">after</emphasis> the superclass has been <link + linkend="mthNewDialogObject">initialized</link>. </para> </section> @@ -115,8 +115,8 @@ The methods in a Rexx dialog object connected to Windows event notifications are commonly called event handlers because the method handles the event. In order to properly code an event handler, the Rexx programmer needs to understand somewhat the underlying mechanism of event notification. This is particularly important in ooDialog 4.2.0 - and later with its ability to <xref linkend="ovvEventsDirectReply"/> invoke the event handling method from the window - <xref linkend="ovvWindowMessages"/> processing loop. + and later with its ability to <link linkend="ovvEventsDirectReply">directly</link> invoke the event handling method from + the window <link linkend="ovvWindowMessages">message</link> processing loop. </para> <para> When the operating system sends an event notification to the underlying dialog, the operating system waits for a reply @@ -759,7 +759,7 @@ <varlistentry><term>lP [optional]</term> <listitem> <para> - The numeric value of the <link linkend="ovvWindowMessages">LPARAM</link>/>) parameter in the window message to match. + The numeric value of the <link linkend="ovvWindowMessages">LPARAM</link> parameter in the window message to match. This defaults to 0. </para> </listitem></varlistentry> @@ -1492,10 +1492,6 @@ and it is not necessary to add the NOTIFY style for those events. </para> <para> - The <emphasis role="italic">connectButtonEvent</emphasis> method is a member of the - <xref linkend="clsEventNotification"/> mixin class. - </para> - <para> Syntax errors are raised when incorrect usage is detected. </para> <para> @@ -6129,10 +6125,6 @@ <varlistentry><term><emphasis role="bold">Details:</emphasis></term> <listitem> <para> - The <emphasis role="italic">connectNotifyEvent</emphasis> method is a member of the - <xref linkend="clsEventNotification"/> mixin class. - </para> - <para> Syntax errors are raised when incorrect usage is detected. </para> <para> @@ -6834,8 +6826,8 @@ raised. </para> <para> - Common guidelines on <link linkend="sctCodingEventHandlers">how</link> to code event handlers are included in the - documentation for the <xref linkend="clsEventNotification"/> class. + 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> When the user interacts with a scroll bar, the operating system does not reposition the scroll box (thumb.) Rather, Modified: docs/trunk/oodialog/en-US/listview.xml =================================================================== --- docs/trunk/oodialog/en-US/listview.xml 2012-11-08 03:21:51 UTC (rev 8575) +++ docs/trunk/oodialog/en-US/listview.xml 2012-11-08 04:15:32 UTC (rev 8576) @@ -316,6 +316,10 @@ <entry>Returns the extended styles of a list-view cont control as the numeric value of the extended style flags.</entry> </row> <row> +<entry><xref linkend="mthGetFullRow"/></entry> +<entry>Returns a <link linkend="clsLvFullRow">LvFullRow</link> object for the specified item in this list view.</entry> +</row> +<row> <entry><xref linkend="mthGetHoverTime"/></entry> <entry>Retrieves the current hover time in milliseconds.</entry> </row> @@ -2676,6 +2680,69 @@ </variablelist> </section> +<section id="mthGetFullRow" xreflabel="getFullRow"><title>getFullRow</title> +<indexterm><primary>getFullRow</primary></indexterm> +<indexterm><primary>ListView class</primary><secondary>getFullRow</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--getFullRow(--itemIndex--)-------------------->< +]]> +</programlisting> + +<para> + Returns a <link linkend="clsLvFullRow">LvFullRow</link> object for the specified item in this list view. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The singel argument is: + </para> + <variablelist> + <varlistentry><term>itemIndex</term> + <listitem> + <para> + The index of the list-view item to get the full row for. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + On success, returns a <computeroutput>LvFullRow</computeroutput> object whose attributes are the attributes of the + list-view item specified. On error the <computeroutput>.nil</computeroutput> object is returne. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + <computeroutput>LvFullRow</computeroutput> objects reflect the attributes of a list-view item and all the subitems of + that item. It is common to think of a row when the list-view is in report view. However, once the subitems are added to a + list-view item, they exist even when the view of the list-view is changed to one of the other views, like icon, or small + icon. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect usage is detected. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example ... +<programlisting> +<![CDATA[ + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End ListView::getFullRow() --> + <section id="mthGetHoverTime" xreflabel="getHoverTime"><title>getHoverTime</title> <indexterm><primary>getHoverTime</primary></indexterm> <programlisting> |
From: <mie...@us...> - 2012-11-16 20:26:49
|
Revision: 8593 http://sourceforge.net/p/oorexx/code-0/8593 Author: miesfeld Date: 2012-11-16 20:26:46 +0000 (Fri, 16 Nov 2012) Log Message: ----------- #496 ooDialog TreeView methods to determine area occupied by an item See ticket [Feature-Requests:#496] Modified Paths: -------------- docs/trunk/oodialog/en-US/tooltip.xml docs/trunk/oodialog/en-US/treeview.xml Modified: docs/trunk/oodialog/en-US/tooltip.xml =================================================================== --- docs/trunk/oodialog/en-US/tooltip.xml 2012-11-16 19:41:52 UTC (rev 8592) +++ docs/trunk/oodialog/en-US/tooltip.xml 2012-11-16 20:26:46 UTC (rev 8593) @@ -48,22 +48,31 @@ <chapter id="clsToolTip"><title>ToolTip Controls</title> <indexterm><primary>ToolTip class</primary></indexterm> <para> - xx + Tooltip controls are pop-up windows that display text. Typically the text describes a <emphasis + role="italic">tool</emphasis>. A <emphasis role="italic">tool</emphasis> is either a window or an application define area + within a window. Conceptually, a ToolTip is a dialog control that contains tools. A ToolTip with no added tool will never + display text. In ooDialog, the tools added to a ToolTip are usually other dialog controls. </para> <para> - xx + ToolTips are hidden most of the time. They appear automatically, or pop up, when the user pauses the mouse pointer over a + tool. The ToolTip appears near the pointer and disappears when the user clicks a mouse button or moves the pointer away + from the tool. </para> <para> - xx + ToolTip controls can display single or multiple lines of text. They can have square or rounded corners. They might or might + not have a stem that points to the tools like a cartoon balloon. ToolTip text can be stationary or can move with the mouse + pointer, called tracking. Stationary text can be displayed adjacent to a tool or it can be displayed over a tool, which is + referred to as in-place. Standard ToolTips are stationary, display a single line of text, have square corners, and have no + stem pointing to the tool. </para> <para> - The <computeroutput>ToolTip</computeroutput> class provides methods to work with and manipulate the underlying - Windows tool tip dialog control which it represents. It is a concrete subclass of the dialog control <link + The <computeroutput>ToolTip</computeroutput> class provides methods to work with and manipulate the underlying Windows + ToolTip dialog control which it represents. It is a concrete subclass of the dialog control <link linkend="chpDialogControlObject">object</link> and therefore has all methods of the of the dialog control object. </para> <para> In addition to the methods of the class itself, the following methods from other classes in the ooDialog framework are - needed, or are useful, when working with tool tip controls: + needed, or are useful, when working with ToolTip controls: <variablelist> <varlistentry><term><emphasis role="bold">Instantiation:</emphasis></term> <listitem> @@ -75,8 +84,8 @@ <varlistentry><term><emphasis role="bold">Dynamic Definition:</emphasis></term> <listitem> <para> - Unlike most other types of dialog controls, a tool tip can not be added to a dialog <link - linkend="ovvDialogTemplate">template</link>. Tool tips are created dynamically during the <link + Unlike most other types of dialog controls, a ToolTip can not be added to a dialog < |
From: <mie...@us...> - 2012-11-17 02:47:55
|
Revision: 8596 http://sourceforge.net/p/oorexx/code-0/8596 Author: miesfeld Date: 2012-11-17 02:47:52 +0000 (Sat, 17 Nov 2012) Log Message: ----------- #495 ooDialog TreeView control has missing styles See ticket [Feature-Requests:#495] Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml docs/trunk/oodialog/en-US/treeview.xml docs/trunk/oodialog/en-US/userdialog.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-17 01:33:16 UTC (rev 8595) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-17 02:47:52 UTC (rev 8596) @@ -7800,12 +7800,13 @@ </simplelist> </para> <variablelist> - <varlistentry><term>BEGINDRAG</term> + <varlistentry id="kywTreeViewBEGINDRAG" xreflabel="BEGINDRAG"><term>BEGINDRAG</term> <listitem> <para> A drag-and-drop operation using the left mouse button was initiated. The documentation for the - <xref linkend="mthDefTreeDragHandler"/>() method contains further information on how to - implement a drag-and-drop handler. + <xref linkend="mthDefTreeDragHandler"/>() method contains further information on how to implement a drag-and-drop + handler. Not that if the tree-view control is give the <xref linkend="styTreeViewNODRAG"/> style, the BEGINDRAG + notification is not sent. </para> </listitem></varlistentry> <varlistentry id="kywTreeViewBEGINEDIT" xreflabel="BEGINEDIT"><term>BEGINEDIT</term> Modified: docs/trunk/oodialog/en-US/treeview.xml =================================================================== --- docs/trunk/oodialog/en-US/treeview.xml 2012-11-17 01:33:16 UTC (rev 8595) +++ docs/trunk/oodialog/en-US/treeview.xml 2012-11-17 02:47:52 UTC (rev 8596) @@ -2951,7 +2951,9 @@ <listitem> <para> The tree-view uses the value for the height of all items. The value itself is the height of a single item. See the <link - linkend="mthGetItemHeight">getItemHeight</link> method. + linkend="mthGetItemHeight">getItemHeight</link> method. By default, the tree-view only allows even heights. However, if + the <link linkend="styTreeViewNONEVENHEIGHT">NONEVENHEIGHT</link> style is give to the tree-view, both odd and even + values can be assigned. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> Modified: docs/trunk/oodialog/en-US/userdialog.xml =================================================================== --- docs/trunk/oodialog/en-US/userdialog.xml 2012-11-17 01:33:16 UTC (rev 8595) +++ docs/trunk/oodialog/en-US/userdialog.xml 2012-11-17 02:47:52 UTC (rev 8596) @@ -10641,37 +10641,50 @@ <simplelist type='vert' columns='3'> <member>ATROOT </member> <member>BUTTONS </member> - <member>LINES </member> + <member>CHECKBOXES </member> <member>EDIT </member> + <member>FULLROWSELECT</member> <member>HSCROLL </member> + <member>INFOTIP </member> + <member>LINES </member> + <member>NODRAG </member> + <member>NOHSCROLL </member> + <member>NONEVENHEIGHT</member> + <member>NOSCROLL </member> + <member>NOTOOLTIPS </member> + <member>RTLREADING </member> + <member>SHOWSELALWAYS</member> + <member>SINGLEEXPAND </member> + <member>TRACKSELECT </member> <member>VSCROLL </member> - <member>SHOWSELALWAYS</member> - <member>INFOTIP </member> <member>ALL </member> - <member>NODRAG </member> <member>HIDDEN </member> <member>DISABLED </member> <member>GROUP </member> - <member>BORDER </member> - <member>TAB </member> + <member>NOBORDER </member> + <member>NOTAB </member> </simplelist> <variablelist> <varlistentry><term>ATROOT</term> <listitem> <para> - The tree view has lines linking child items to the root of the hierarchy. + The tree-view has lines linking child items to the root of the hierarchy. </para> </listitem></varlistentry> <varlistentry id="styTreeViewBUTTONS" xreflabel="BUTTONS"><term>BUTTONS</term> <listitem> <para> - The tree view adds a button to the left of each parent item. + Displays plus (+) and minus (-) buttons next to parent items. The user clicks the buttons to expand or collapse a + parent item's list of child items. To include buttons with items at the root of the tree view, the LINES style must + also be specified. </para> </listitem></varlistentry> - <varlistentry><term>LINES</term> + <varlistentry id="styTreeViewCHECKBOXES" xreflabel="CHECKBOXES"><term>CHECKBOXES</term> <listitem> <para> - The tree view has lines linking child items to their corresponding parent items. + Displays a check box with the item. In earlier versions of Windows, the check box would only be displayed if the + tree-view item had an image associated with it. If ooDialog is running on Windows XP or later this earlier + behaviour no longer applies. </para> </listitem></varlistentry> <varlistentry id="styTreeViewEDIT" xreflabel="EDIT"><term>EDIT</term> @@ -10680,52 +10693,114 @@ With this style, the tree-view allows the user to edit the tree-view item labels. To have an edited label take effect, the programmer must connect an <link linkend="ovvEvents">event</link> notification using the <xref linkend="mthConnectTreeViewEvent"/> method. For the most flexibility with edit labeling, connect both the <xref - linkend="kywTreeViewBEGINEDIT"/> and <xref linkend="kywTreeViewENDEDIT"/> notifications. Alternatively the <xref + linkend="kywTreeViewBEGINEDIT"/> and <xref linkend="kywTreeViewENDEDIT"/> notifications. Alternatively the <xref linkend="kywTreeViewDEFAULTEDIT"/> event could be connected using the <emphasis role="italic">connectListViewEvent</emphasis> method. </para> </listitem></varlistentry> - <varlistentry><term>HSCROLL</term> + <varlistentry id="styTreeViewFULLROWSELECT" xreflabel="FULLROWSELECT"><term>FULLROWSELECT</term> <listitem> <para> - The tree view supports a horizontal scroll bar. + Enables full-row selection in the tree view. The entire row of the selected item is highlighted, and clicking + anywhere on an item's row causes it to be selected. This style cannot be used in conjunction with the LINES + style. </para> </listitem></varlistentry> - <varlistentry><term>VSCROLL</term> + <varlistentry><term>HSCROLL</term> <listitem> <para> - The tree view supports a vertical scroll bar. + The tree view supports a horizontal scroll bar. </para> </listitem></varlistentry> - <varlistentry id='styTreeViewInfoTip'><term>INFOTIP</term> + <varlistentry id='styTreeViewINFOTIP'><term>INFOTIP</term> <listitem> <para> The tree-view will request info tip text by sending the <link linkend="kywTreeViewGETINFOTIP">GETINFOTIP</link> notification. If the tree-view does not have the INFOTIP style, GETINFOTIP notifications are not sent. </para> </listitem></varlistentry> + <varlistentry><term>LINES</term> + <listitem> + <para> + The tree-view has lines linking child items to their corresponding parent items. + </para> + </listitem></varlistentry> + <varlistentry id='styTreeViewNODRAG'><term>NODRAG</term> + <listitem> + <para> + The tree-view is prevented from sending <xref linkend="kywTreeViewBEGINDRAG"/> notifications. + </para> + </listitem></varlistentry> + <varlistentry id="styTreeViewNOHSCROLL" xreflabel="NOHSCROLL"><term>NOHSCROLL</term> + <listitem> + <para> + Disables horizontal scrolling in the control. The control will not display any horizontal scroll bars. + </para> + </listitem></varlistentry> + <varlistentry id="styTreeViewNONEVENHEIGHT" xreflabel="NONEVENHEIGHT"><term>NONEVENHEIGHT</term> + <listitem> + <para> + Allows setting the height of the items to an odd height with the <link + linkend="mthSetItemHeight">setItemHeight</link>. By default, the height of items must be an even value. + </para> + </listitem></varlistentry> + <varlistentry id="styTreeViewNOSCROLL" xreflabel="NOSCROLL"><term>NOSCROLL</term> + <listitem> + <para> + Disables both horizontal and vertical scrolling in the tree-view. The control will not display any scroll bars. + </para> + </listitem></varlistentry> + <varlistentry id="styTreeViewNOTOOLTIPS" xreflabel="NOTOOLTIPS"><term>NOTOOLTIPS</term> + <listitem> + <para> + By default, a tree-view always creates a child ToolTip. This style prevents the creation of a ToolTip. + </para> + </listitem></varlistentry> + <varlistentry id="styTreeViewRTLREADING" xreflabel="RTLREADING"><term>RTLREADING</term> + <listitem> + <para> + Causes text to be displayed from right-to-left (RTL). Usually, windows display text left-to-right (LTR). Windows + can be mirrored to display languages such as Hebrew or Arabic that read RTL. Typically, tree-view text is displayed + in the same direction as the text in its parent window. If RTLREADING is set, tree-view text reads in the opposite + direction from the text in the parent window. + </para> + </listitem></varlistentry> <varlistentry><term>SHOWSELALWAYS</term> <listitem> <para> A selected item remains selected when the tree view loses focus. </para> </listitem></varlistentry> - <varlistentry><term>ALL</term> + <varlistentry id="styTreeViewSINGLEEXPAND" xreflabel="SINGLEEXPAND"><term>SINGLEEXPAND</term> <listitem> <para> - The options ATROOT, BUTTONS, LINES, EDIT, HSCROLL, and SHOWSELALWAYS are all applied. + Causes the item being selected to expand and the item being unselected to collapse upon selection in the tree + view. If the user holds down the CTRL key while selecting an item, the item being unselected will not be + collapsed. </para> </listitem></varlistentry> - <varlistentry><term>NODRAG</term> + <varlistentry id="styTreeViewTRACKSELECT" xreflabel="TRACKSELECT"><term>TRACKSELECT</term> <listitem> <para> - e tree view is prevented from sending "begin drag" notifications. + Enables hot tracking in a tree-view control. </para> </listitem></varlistentry> + <varlistentry><term>VSCROLL</term> + <listitem> + <para> + The tree view supports a vertical scroll bar. + </para> + </listitem></varlistentry> + <varlistentry><term>ALL</term> + <listitem> + <para> + The styles ATROOT, BUTTONS, EDIT, HSCROLL, LINES, SHOWSELALWAYS, and VSROLL are all applied. + </para> + </listitem></varlistentry> <varlistentry><term>HIDDEN</term> <listitem> <para> - The tree view has not <xref linkend="wsvisible"/> window style. + The tree view has the not <xref linkend="wsvisible"/> window style. </para> </listitem></varlistentry> <varlistentry><term>DISABLED</term> |
From: <mie...@us...> - 2012-11-17 04:43:33
|
Revision: 8597 http://sourceforge.net/p/oorexx/code-0/8597 Author: miesfeld Date: 2012-11-17 04:43:31 +0000 (Sat, 17 Nov 2012) Log Message: ----------- ooDialog - incrmental doc update Modified Paths: -------------- docs/trunk/oodialog/en-US/listview.xml docs/trunk/oodialog/en-US/treeview.xml Modified: docs/trunk/oodialog/en-US/listview.xml =================================================================== --- docs/trunk/oodialog/en-US/listview.xml 2012-11-17 02:47:52 UTC (rev 8596) +++ docs/trunk/oodialog/en-US/listview.xml 2012-11-17 04:43:31 UTC (rev 8597) @@ -528,6 +528,10 @@ <entry>Changes the text of an item, or the text of a subitem, of a list-view item.</entry> </row> <row> +<entry><xref linkend="mthSetToolTipsClsListView"/></entry> +<entry>Sets the child <link linkend="clsToolTip">ToolTip</link> control used by this tree-view.</entry> +</row> +<row> <entry><xref linkend="mthSmalSpacing"/></entry> <entry>Determines the spacing between items in a list-view control when it has the small-icon style.</entry> </row> @@ -3406,33 +3410,10 @@ <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - Returns the child Rexx tool-tip object, or the <computeroutput>.nil</computeroutput> object if the list-view does not - have a child tool tip control. + Returns the child Rexx <computeroutput>ToolTip</computeroutput> object, or the <computeroutput>.nil</computeroutput> + object if the list-view does not have a child tool tip control. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> - <listitem> - <para> - Additional comments. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details</emphasis></term> - <listitem> - <para> - Raises syntax errors when incorrect usage is detected. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> - <listitem> - <para> - This example ... -<programlisting> -<![CDATA[ - -]]> -</programlisting> - </para> - </listitem></varlistentry> </variablelist> </section> <!-- End ListView::getToolTips() --> @@ -6356,6 +6337,52 @@ </variablelist> </section> + +<section id="mthSetToolTipsClsListView" xreflabel="setToolTips"><title>setToolTips</title> +<indexterm><primary>setToolTips</primary><secondary>ListView class</secondary></indexterm> +<indexterm><primary>ListView class</primary><secondary>setToolTips</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--setToolTips(--toolTip--)--------------------->< +]]> +</programlisting> + +<para> + Sets the child <link linkend="clsToolTip">ToolTip</link> control used by this list-view. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The arguments are: + </para> + <variablelist> + <varlistentry><term>toolTip [required]</term> + <listitem> + <para> + The Rexx <computeroutput>ToolTip</computeroutput> object that represents the tool tip control the list-view should + use. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + Returns the previous tool tip, as a Rexx <computeroutput>ToolTip</computeroutput> object, or the + <computeroutput>.nil</computeroutput> object if there is no previous tool tip. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect usage is detected. + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End ListView::setToolTips() --> + + <section id="mthSmalSpacing" xreflabel="smallSpacing"><title>smallSpacing</title> <indexterm><primary>smallSpacing</primary></indexterm> <programlisting> Modified: docs/trunk/oodialog/en-US/treeview.xml =================================================================== --- docs/trunk/oodialog/en-US/treeview.xml 2012-11-17 02:47:52 UTC (rev 8596) +++ docs/trunk/oodialog/en-US/treeview.xml 2012-11-17 04:43:31 UTC (rev 8597) @@ -124,56 +124,56 @@ <entry>Adds a new item to the tree-view.</entry> </row> <row> +<entry><xref linkend="child"/></entry> <entry>Child</entry> -<entry><xref linkend="child"/></entry> </row> <row> +<entry><xref linkend="collapse"/></entry> <entry>Collapse</entry> -<entry><xref linkend="collapse"/></entry> </row> <row> +<entry><xref linkend="collapseandreset"/></entry> <entry>CollapseAndReset</entry> -<entry><xref linkend="collapseandreset"/></entry> </row> <row> +<entry><xref linkend="deletetrc"/></entry> <entry>delete</entry> -<entry><xref linkend="deletetrc"/></entry> </row> <row> +<entry><xref linkend="deletealltrc"/></entry> <entry>deleteAll</entry> -<entry><xref linkend="deletealltrc"/></entry> </row> <row> +<entry><xref linkend="drophighlight"/></entry> <entry>DropHighlight</entry> -<entry><xref linkend="drophighlight"/></entry> </row> <row> +<entry><xref linkend="drophighlightedtrc"/></entry> <entry>dropHighlighted</entry> -<entry><xref linkend="drophighlightedtrc"/></entry> </row> <row> +<entry><xref linkend="edittrc"/></entry> <entry>Edit</entry> -<entry><xref linkend="edittrc"/></entry> </row> <row> +<entry><xref linkend="mthEndEditClsTreeView"/></entry> <entry>endEdit</entry> -<entry><xref linkend="mthEndEditClsTreeView"/></entry> </row> <row> +<entry><xref linkend="mthEnsureVisibleClsTreeView"/></entry> <entry>ensureVisible</entry> -<entry><xref linkend="mthEnsureVisibleClsTreeView"/></entry> </row> <row> +<entry><xref linkend="expand"/></entry> <entry>Expand</entry> -<entry><xref linkend="expand"/></entry> </row> <row> <entry><xref linkend="mthFind"/></entry> <entry>Finds the first tree-view item whose label matches the text specified. The search is case insensitive.</entry> </row> <row> +<entry><xref linkend="firstvisibletrc"/></entry> <entry>firstVisible</entry> -<entry><xref linkend="firstvisibletrc"/></entry> </row> <row> <entry><xref linkend="mthGetImageListClsTreeView"/></entry> @@ -192,88 +192,92 @@ <entry>Retrieves the bounding rectangle for a tree-view item and indicates whether the item is visible.</entry> </row> <row> +<entry><xref linkend="mthGetToolTipsClsTreeView"/></entry> +<entry>Retrieves the child <link linkend="clsToolTip">ToolTip</link> control used by this tree-view.</entry> +</row> +<row> <entry><xref linkend="mthItemTextClsTreeView"/></entry> <entry>Gets the text, the label, of the specified tree-view item.</entry> </row> <row> -<entry>HitTest</entry> -<entry><xref linkend="hittest"/></entry> +<entry><xref linkend="mthHitTestClsTreeView"/></entry> +<entry>hitTest</entry> </row> <row> <entry><xref linkend="mthHitTestInfoClsTreeView"/></entry> <entry>Determines the location of a point relative to the tree-view control.</entry> </row> <row> +<entry><xref linkend="indent"/></entry> <entry>Indent</entry> -<entry><xref linkend="indent"/></entry> </row> <row> +<entry><xref linkend="indentnew"/></entry> <entry>Indent=</entry> -<entry><xref linkend="indentnew"/></entry> </row> <row> <entry><xref linkend="mthInsertClsTreeView"/></entry> <entry>Inserts a new item into the tree-view control.</entry> </row> <row> +<entry><xref linkend="isancestor"/></entry> <entry>IsAncestor</entry> -<entry><xref linkend="isancestor"/></entry> </row> <row> <entry><xref linkend="mthItemInfoClsTreeView"/></entry> <entry>The <emphasis role="italic">itemInfo</emphasis> method returnes the attributes of the specified item as a stem.</entry> </row> <row> +<entry><xref linkend="itemstrc"/></entry> <entry>items</entry> -<entry><xref linkend="itemstrc"/></entry> </row> <row> +<entry><xref linkend="makefirstvisibletrc"/></entry> <entry>MakeFirstVisible</entry> -<entry><xref linkend="makefirstvisibletrc"/></entry> </row> <row> <entry><xref linkend="mthModifyClsTreeView"/></entry> <entry>Modifies some or all of an item's attributes.</entry> </row> <row> +<entry><xref linkend="moveitem"/></entry> <entry>moveItem</entry> -<entry><xref linkend="moveitem"/></entry> </row> <row> +<entry><xref linkend="nexttrc"/></entry> <entry>next</entry> -<entry><xref linkend="nexttrc"/></entry> </row> <row> +<entry><xref linkend="nextvisible"/></entry> <entry>NextVisible</entry> -<entry><xref linkend="nextvisible"/></entry> </row> <row> +<entry><xref linkend="parent"/></entry> <entry>Parent</entry> -<entry><xref linkend="parent"/></entry> </row> <row> +<entry><xref linkend="previoustrc"/></entry> <entry>previous</entry> -<entry><xref linkend="previoustrc"/></entry> </row> <row> +<entry><xref linkend="previousvisible"/></entry> <entry>PreviousVisible</entry> -<entry><xref linkend="previousvisible"/></entry> </row> <row> <entry><xref linkend="mthRemoveItemDataClsTreeView"/></entry> <entry>Removes and returns the user data associated with the specified tree-view item.</entry> </row> <row> +<entry><xref linkend="mthRoot"/></entry> <entry>Root</entry> -<entry><xref linkend="mthRoot"/></entry> </row> <row> +<entry><xref linkend="selecttrc"/></entry> <entry>select</entry> -<entry><xref linkend="selecttrc"/></entry> </row> <row> +<entry><xref linkend="selectedtrc"/></entry> <entry>selected</entry> -<entry><xref linkend="selectedtrc"/></entry> </row> <row> <entry><xref linkend="mthSetImageListClsTreeView"/></entry> @@ -288,20 +292,24 @@ <entry>Sets the height of the tree-view items.</entry> </row> <row> +<entry><xref linkend="mthSetToolTipsClsTreeView"/></entry> +<entry>Sets the child <link linkend="clsToolTip">ToolTip</link> control used by this tree-view.</entry> +</row> +<row> +<entry><xref linkend="sortchildren"/></entry> <entry>SortChildren</entry> -<entry><xref linkend="sortchildren"/></entry> </row> <row> <entry><xref linkend="mthSortChildrenCB"/></entry> <entry>Has the tree-view sort the children of the specified item by invoking a custom comparsion method in the Rexx dialog.</entry> </row> <row> +<entry><xref linkend="toggle"/></entry> <entry>Toggle</entry> -<entry><xref linkend="toggle"/></entry> </row> <row> +<entry><xref linkend="visibleitems"/></entry> <entry>VisibleItems</entry> -<entry><xref linkend="visibleitems"/></entry> </row> </tbody></tgroup> </table> @@ -1344,17 +1352,44 @@ </section> <!-- End TreeView::getItemRect() --> -<section id="hittest"><title>HitTest</title> -<indexterm><primary>HitTest</primary></indexterm> +<section id="mthGetToolTipsClsTreeView" xreflabel="getToolTips"><title>getToolTips</title> +<indexterm><primary>getToolTips</primary><secondary>TreeView class</secondary></indexterm> +<indexterm><primary>TreeView class</primary><secondary>getToolTips</secondary></indexterm> <programlisting> <![CDATA[ ->>--hitTest(--x--,--y--)------------------------->< +>>--getToolTips---------------------------------->< +]]> +</programlisting> +<para> + Retrieves the child <link linkend="clsToolTip">ToolTip</link> control used by this tree-view. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + There are no arguments for this method + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + Returns the Rexx <link linkend="clsToolTip">ToolTip</link> object that represents the ToolTip control of the tree-view, + or the <computeroutput>.nil</computeroutput> object if the tree-view does not currently have a ToolTip. + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End TreeView::getToolTips() --> +<section id="mthHitTestClsTreeView"><title>hitTest</title> +<indexterm><primary>hitTest</primary></indexterm> +<programlisting> +<![CDATA[ +>>--hitTest(--x--,--y--)------------------------->< ]]> </programlisting> -<para>The HitTest method determines the location of the +<para>The hitTest method determines the location of the specified point relative to the <xref linkend="defClientArea"/> of a tree-view control.</para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -2403,46 +2438,7 @@ </variablelist> </section> -<section id="parent"><title>Parent</title> -<indexterm><primary>Parent</primary></indexterm> -<programlisting> -<![CDATA[ ->>--parent(--hItem--)---------------------------->< - -]]> -</programlisting> - -<para>The Parent method retrieves the parent of the specified -item.</para> -<variablelist> -<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> -<listitem><para>The only argument is: -<variablelist> -<varlistentry><term>hItem</term> -<listitem><para>The handle to the item for which the parent is to be retrieved. -</para></listitem></varlistentry> -</variablelist> -</para></listitem></varlistentry> -<varlistentry><term><emphasis role="bold">Return value:</emphasis></term> -<listitem><para>The handle to the parent item, or -1 if -<emphasis role="italic">hItem</emphasis> is not -specified or is 0, or 0 in all other cases. -</para></listitem></varlistentry> -<varlistentry><term><emphasis role="bold">Example:</emphasis></term> -<listitem><para>The following example displays the name of the selected item's parent: -<programlisting> -<![CDATA[ -::method Parent - curTree = self~newTreeView("IDC_TREE") - itemInfo. = curTree~itemInfo(curTree~Parent(curTree~selected)) - say ItemInfo.!Text -]]> -</programlisting> -</para></listitem></varlistentry> -</variablelist> -</section> - <section id="nexttrc"><title>next</title> <indexterm><primary>next</primary> <secondary>TreeView class</secondary></indexterm> @@ -2517,6 +2513,47 @@ </variablelist> </section> + +<section id="parent"><title>Parent</title> +<indexterm><primary>Parent</primary></indexterm> +<programlisting> +<![CDATA[ +>>--parent(--hItem--)---------------------------->< + + +]]> +</programlisting> + +<para>The Parent method retrieves the parent of the specified +item.</para> +<variablelist> +<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> +<listitem><para>The only argument is: +<variablelist> +<varlistentry><term>hItem</term> +<listitem><para>The handle to the item for which the parent is to be retrieved. +</para></listitem></varlistentry> +</variablelist> +</para></listitem></varlistentry> +<varlistentry><term><emphasis role="bold">Return value:</emphasis></term> +<listitem><para>The handle to the parent item, or -1 if +<emphasis role="italic">hItem</emphasis> is not +specified or is 0, or 0 in all other cases. +</para></listitem></varlistentry> +<varlistentry><term><emphasis role="bold">Example:</emphasis></term> +<listitem><para>The following example displays the name of the selected item's parent: +<programlisting> +<![CDATA[ +::method Parent + curTree = self~newTreeView("IDC_TREE") + itemInfo. = curTree~itemInfo(curTree~Parent(curTree~selected)) + say ItemInfo.!Text +]]> +</programlisting> +</para></listitem></varlistentry> +</variablelist> +</section> + <section id="previoustrc"><title>previous</title> <indexterm><primary>previous</primary> <secondary>TreeView class</secondary></indexterm> @@ -2980,7 +3017,51 @@ </variablelist> </section> <!-- End TreeView::setItemHeight() --> +<section id="mthSetToolTipsClsTreeView" xreflabel="setToolTips"><title>setToolTips</title> +<indexterm><primary>setToolTips</primary><secondary>TreeView class</secondary></indexterm> +<indexterm><primary>TreeView class</primary><secondary>setToolTips</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--setToolTips(--toolTip--)--------------------->< +]]> +</programlisting> +<para> + Sets the child <link linkend="clsToolTip">ToolTip</link> control used by this tree-view. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The arguments are: + </para> + <variablelist> + <varlistentry><term>toolTip [required]</term> + <listitem> + <para> + The Rexx <computeroutput>ToolTip</computeroutput> object that represents the tool tip control the tree-view should + use. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + Returns the previous tool tip, as a Rexx <computeroutput>ToolTip</computeroutput> object, or the + <computeroutput>.nil</computeroutput> object if there is no previous tool tip. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect usage is detected. + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End TreeView::setToolTips() --> + + <section id="sortchildren"><title>SortChildren</title> <indexterm><primary>SortChildren</primary></indexterm> <programlisting> |
From: <mie...@us...> - 2012-11-17 05:00:12
|
Revision: 8598 http://sourceforge.net/p/oorexx/code-0/8598 Author: miesfeld Date: 2012-11-17 05:00:09 +0000 (Sat, 17 Nov 2012) Log Message: ----------- ooDialog doc, fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml docs/trunk/oodialog/en-US/tab.xml docs/trunk/oodialog/en-US/treeview.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-17 04:43:31 UTC (rev 8597) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-17 05:00:09 UTC (rev 8598) @@ -7882,7 +7882,7 @@ <listitem> <para> The tree-view control is requesting text to display an info tip. The notification is only sent when the tree-view - control has the <link linkend="styTreeViewInfoTip">INFOTIP</link> style. + control has the <link linkend="styTreeViewINFOTIP">INFOTIP</link> style. </para> </listitem></varlistentry> <varlistentry><term>KEYDOWN</term> Modified: docs/trunk/oodialog/en-US/tab.xml =================================================================== --- docs/trunk/oodialog/en-US/tab.xml 2012-11-17 04:43:31 UTC (rev 8597) +++ docs/trunk/oodialog/en-US/tab.xml 2012-11-17 05:00:09 UTC (rev 8598) @@ -175,7 +175,7 @@ <entry>Retrieves the current image list from the tab control, if there is one.</entry> </row> <row> -<entry><xref linkend="mthGetItemRect"/></entry> +<entry><xref linkend="mthGetItemRectClsTab"/></entry> <entry>Gets the bounding rectangle for a tab in a tab control.</entry> </row> <row> @@ -800,8 +800,8 @@ </variablelist> </section> <!-- End TabControl::getImageList() --> -<section id="mthGetItemRect" xreflabel="getItemRect"><title>getItemRect</title> -<indexterm><primary>getItemRect</primary></indexterm> +<section id="mthGetItemRectClsTab" xreflabel="getItemRect"><title>getItemRect</title> +<indexterm><primary>getItemRect</primary<secondary>Tab class</secondary></indexterm> <indexterm><primary>Tab class</primary><secondary>getItemRect</secondary></indexterm> <programlisting> <![CDATA[ Modified: docs/trunk/oodialog/en-US/treeview.xml =================================================================== --- docs/trunk/oodialog/en-US/treeview.xml 2012-11-17 04:43:31 UTC (rev 8597) +++ docs/trunk/oodialog/en-US/treeview.xml 2012-11-17 05:00:09 UTC (rev 8598) @@ -188,7 +188,7 @@ <entry>Gets the height the tree-view control used for each of items items.</entry> </row> <row> -<entry><xref linkend="mthGetItemRect"/></entry> +<entry><xref linkend="mthGetItemRectClsTreeView"/></entry> <entry>Retrieves the bounding rectangle for a tree-view item and indicates whether the item is visible.</entry> </row> <row> @@ -1255,8 +1255,8 @@ </variablelist> </section> <!-- End TreeView::getItemHeight() --> -<section id="mthGetItemRect" xreflabel="getItemRect"><title>getItemRect</title> -<indexterm><primary>getItemRect</primary></indexterm> +<section id="mthGetItemRectClsTreeView" xreflabel="getItemRect"><title>getItemRect</title> +<indexterm><primary>getItemRect</primary><secondary>TreeView class</secondary></indexterm> <indexterm><primary>TreeView class</primary><secondary>getItemRect</secondary></indexterm> <programlisting> <![CDATA[ |
From: <mie...@us...> - 2012-11-21 01:33:14
|
Revision: 8608 http://sourceforge.net/p/oorexx/code-0/8608 Author: miesfeld Date: 2012-11-21 01:33:11 +0000 (Wed, 21 Nov 2012) Log Message: ----------- ooDialog doc, fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/dialogExtensions.xml docs/trunk/oodialog/en-US/dialogObject.xml docs/trunk/oodialog/en-US/monthcalendar.xml docs/trunk/oodialog/en-US/propertySheetDialogs.xml docs/trunk/oodialog/en-US/tooltip.xml docs/trunk/oodialog/en-US/utilityclasses.xml docs/trunk/oodialog/en-US/windowBase.xml docs/trunk/oodialog/en-US/windowBaseDCO.xml docs/trunk/oodialog/en-US/windowBaseDO.xml Modified: docs/trunk/oodialog/en-US/dialogExtensions.xml =================================================================== --- docs/trunk/oodialog/en-US/dialogExtensions.xml 2012-11-21 01:14:33 UTC (rev 8607) +++ docs/trunk/oodialog/en-US/dialogExtensions.xml 2012-11-21 01:33:11 UTC (rev 8608) @@ -2515,7 +2515,7 @@ <listitem><para>Shows the dialog </para></listitem></varlistentry> <varlistentry><term>NOREDRAW</term> -<listitem><para>Moves the dialog control without updating the display. Use the <xref linkend="mthUpdate"/> +<listitem><para>Moves the dialog control without updating the display. Use the <xref linkend="mthUpdateClsWindowBase"/> method to manually update the display. </para></listitem></varlistentry> </variablelist> @@ -3192,7 +3192,7 @@ <listitem><para>Shows the control. </para></listitem></varlistentry> <varlistentry><term>NOREDRAW</term> -<listitem><para>Resizes the control without updating the display. Use the <xref linkend="mthUpdate"/> method +<listitem><para>Resizes the control without updating the display. Use the <xref linkend="mthUpdateClsWindowBase"/> method to manually update the display. </para></listitem></varlistentry> </variablelist> Modified: docs/trunk/oodialog/en-US/dialogObject.xml =================================================================== --- docs/trunk/oodialog/en-US/dialogObject.xml 2012-11-21 01:14:33 UTC (rev 8607) +++ docs/trunk/oodialog/en-US/dialogObject.xml 2012-11-21 01:33:11 UTC (rev 8608) @@ -5118,7 +5118,7 @@ <listitem><para>Shows the dialog </para></listitem></varlistentry> <varlistentry><term>NOREDRAW</term> -<listitem><para>Center the dialog without updating the display. Use the <xref linkend="mthUpdate"/> method +<listitem><para>Center the dialog without updating the display. Use the <xref linkend="mthUpdateClsWindowBase"/> method to manually update the display. </para></listitem></varlistentry> </variablelist> @@ -5812,7 +5812,7 @@ <para>The hideWindowFast method is similar to the <xref linkend="mthHideWindow"/> method, but it is faster because the window's or item's area is not redrawn. The hideWindowFast method is used when more than one state is modified. After the operations, you can -manually redraw the dialog window, using the <xref linkend="mthUpdate"/> method. </para> +manually redraw the dialog window, using the <xref linkend="mthUpdateClsWindowBase"/> method. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem><para>The only argument is: Modified: docs/trunk/oodialog/en-US/monthcalendar.xml =================================================================== --- docs/trunk/oodialog/en-US/monthcalendar.xml 2012-11-21 01:14:33 UTC (rev 8607) +++ docs/trunk/oodialog/en-US/monthcalendar.xml 2012-11-21 01:33:11 UTC (rev 8608) @@ -223,7 +223,7 @@ <entry>Retrieves the date information for the date specified as <emphasis role="italic">today</emphasis> for the month calendar control.</entry> </row> <row> -<entry><xref linkend="mthHitTest"/></entry> +<entry><xref linkend="mthHitTestClsMonthCalendar"/></entry> <entry>Determines which portion of a month calendar control is at a given point on the screen.</entry> </row> <row> @@ -1846,8 +1846,8 @@ </section> <!-- End MonthCalendar::getToday() --> -<section id="mthHitTest" xreflabel="hitTest"><title>hitTest</title> -<indexterm><primary>hitTest</primary></indexterm> +<section id="mthHitTestClsMonthCalendar" xreflabel="hitTest"><title>hitTest</title> +<indexterm><primary>hitTest</primary><secondary>MonthCalendary class</secondary></indexterm> <indexterm><primary>MonthCalendar class</primary><secondary>hitTest</secondary></indexterm> <programlisting> <![CDATA[ Modified: docs/trunk/oodialog/en-US/propertySheetDialogs.xml =================================================================== --- docs/trunk/oodialog/en-US/propertySheetDialogs.xml 2012-11-21 01:14:33 UTC (rev 8607) +++ docs/trunk/oodialog/en-US/propertySheetDialogs.xml 2012-11-21 01:33:11 UTC (rev 8608) @@ -1587,7 +1587,7 @@ <listitem> <para> This is not a <emphasis role="italic">dynamic</emphasis> attribute. I.e., if the underlying property sheet has its - title bar caption changed, say through the <xref linkend="mthSetTitle"/> method, the value of the + title bar caption changed, say through the <xref linkend="mthSetTitleClsWindowBase"/> method, the value of the <emphasis role="italic">caption</emphasis> attribute will not change. Likewise, if the programmer were to change the value of this attribute after the underlying dialog was created, it would not change the title bar of the dialog. At the time the underlying dialog is created, this attribute is used to set the dialog's title bar. Other than that, Modified: docs/trunk/oodialog/en-US/tooltip.xml =================================================================== --- docs/trunk/oodialog/en-US/tooltip.xml 2012-11-21 01:14:33 UTC (rev 8607) +++ docs/trunk/oodialog/en-US/tooltip.xml 2012-11-21 01:33:11 UTC (rev 8608) @@ -257,7 +257,7 @@ <entry>x</entry> </row> <row> -<entry><xref linkend="mthCurrentToolInfo"/></entry> +<entry><xref linkend="mthGetCurrentToolInfo"/></entry> <entry>x</entry> </row> <row> @@ -273,7 +273,7 @@ <entry>x</entry> </row> <row> -<entry><xref linkend="mthGetText"/></entry> +<entry><xref linkend="mthGetTextClsToolTip"/></entry> <entry>x</entry> </row> <row> @@ -301,7 +301,7 @@ <entry>x</entry> </row> <row> -<entry><xref linkend="mthHitTest"/></entry> +<entry><xref linkend="mthHitTestClsToolTip"/></entry> <entry>x</entry> </row> <row> @@ -333,7 +333,7 @@ <entry>x</entry> </row> <row> -<entry><xref linkend="mthTipBkColor"/></entry> +<entry><xref linkend="mthSetTipBkColor"/></entry> <entry>x</entry> </row> <row> @@ -341,7 +341,7 @@ <entry>x</entry> </row> <row> -<entry><xref linkend="mthSetTitle"/></entry> +<entry><xref linkend="mthSetTitleClsToolTip"/></entry> <entry>x</entry> </row> <row> @@ -361,7 +361,7 @@ <entry>x</entry> </row> <row> -<entry><xref linkend="mthUpdate"/></entry> +<entry><xref linkend="mthUpdateClsToolTip"/></entry> <entry>x</entry> </row> <row> @@ -1173,8 +1173,8 @@ </section> <!-- End ToolTip::getMaxTipWidth() --> -<section id="mthGetText" xreflabel="getText"><title>getText</title> -<indexterm><primary>getText</primary></indexterm> +<section id="mthGetTextClsToolTip" xreflabel="getText"><title>getText</title> +<indexterm><primary>getText</primary><secondary>ToolTip class</secondary></indexterm> <indexterm><primary>ToolTip class</primary><secondary>getText</secondary></indexterm> <programlisting> <![CDATA[ @@ -1621,8 +1621,8 @@ </section> <!-- End ToolTip::hasCurrentTool() --> -<section id="mthHitTest" xreflabel="hitTest"><title>hitTest</title> -<indexterm><primary>hitTest</primary></indexterm> +<section id="mthHitTestClsToolTip" xreflabel="hitTest"><title>hitTest</title> +<indexterm><primary>hitTest</primary><secondary>ToolTip class</secondary></indexterm> <indexterm><primary>ToolTip class</primary><secondary>hitTest</secondary></indexterm> <programlisting> <![CDATA[ @@ -2261,8 +2261,8 @@ </section> <!-- End ToolTip::setTipTextColor() --> -<section id="mthSetTitle" xreflabel="setTitle"><title>setTitle</title> -<indexterm><primary>setTitle</primary></indexterm> +<section id="mthSetTitleClsToolTip" xreflabel="setTitle"><title>setTitle</title> +<indexterm><primary>setTitle</primary><secondary>ToolTip class</secondary></indexterm> <indexterm><primary>ToolTip class</primary><secondary>setTitle</secondary></indexterm> <programlisting> <![CDATA[ @@ -2581,8 +2581,8 @@ </section> <!-- End ToolTip::trackPosition() --> -<section id="mthUpdate" xreflabel="update"><title>update</title> -<indexterm><primary>update</primary></indexterm> +<section id="mthUpdateClsToolTip" xreflabel="update"><title>update</title> +<indexterm><primary>update</primary><secondary>ToolTip class</secondary></indexterm> <indexterm><primary>ToolTip class</primary><secondary>update</secondary></indexterm> <programlisting> <![CDATA[ @@ -2709,7 +2709,7 @@ </section> <!-- End ToolTip::updateTipText() --> -<section id="clsToolInf" xreflabel="ToolInf"><title>ToolInfo Class</title> +<section id="clsToolInfo" xreflabel="ToolInf"><title>ToolInfo Class</title> <indexterm><primary>ToolInfo class</primary></indexterm> <para> A <emphasis role="italic">ToolInfo</emphasis> object contains information about a tool in a <xref linkend="clsToolTip"/> Modified: docs/trunk/oodialog/en-US/utilityclasses.xml =================================================================== --- docs/trunk/oodialog/en-US/utilityclasses.xml 2012-11-21 01:14:33 UTC (rev 8607) +++ docs/trunk/oodialog/en-US/utilityclasses.xml 2012-11-21 01:33:11 UTC (rev 8608) @@ -10911,7 +10911,7 @@ <section id="wbwSetTitle" xreflabel="setTitle"><title>setTitle</title> <programlisting> -WindowBase::<xref linkend="mthSetTitle"/> +WindowBase::<xref linkend="mthSetTitleClsWindowBase"/> <![CDATA[ >>--setTitle(--newText--)------------------------>< @@ -10955,7 +10955,7 @@ <section id="wbwUpdate" xreflabel="update"><title>update</title> <programlisting> -WindowBase::<xref linkend="mthUpdate"/> +WindowBase::<xref linkend="mthUpdateClsWindowBase"/> <![CDATA[ ]]> Modified: docs/trunk/oodialog/en-US/windowBase.xml =================================================================== --- docs/trunk/oodialog/en-US/windowBase.xml 2012-11-21 01:14:33 UTC (rev 8607) +++ docs/trunk/oodialog/en-US/windowBase.xml 2012-11-21 01:33:11 UTC (rev 8608) @@ -265,7 +265,7 @@ <entry>Sets the text, the caption, of the dialog.</entry> </row> <row> -<entry><xref linkend="mthSetTitle"/></entry> +<entry><xref linkend="mthSetTitleClsWindowBase"/></entry> <entry>Sets the text of the dialog.</entry> </row> <row> @@ -289,7 +289,7 @@ <entry>Sets the text of the dialog.</entry> </row> <row> -<entry><xref linkend="mthUpdate"/></entry> +<entry><xref linkend="mthUpdateClsWindowBase"/></entry> <entry>Invalidates the entire client area of the dialog.</entry> </row> <row> @@ -1294,7 +1294,7 @@ </programlisting> This is usually done when there are a number of controls to make visible at one time. The programmer would make - them all visible without redrawing. Then use the <xref linkend="mthUpdate"/> method to schedule + them all visible without redrawing. Then use the <xref linkend="mthUpdateClsWindowBase"/> method to schedule repainting everything at once. </para> </listitem></varlistentry> @@ -1961,8 +1961,8 @@ </section> <section id="mthGetText" xreflabel="getText"><title>getText</title> -<indexterm><primary>getText</primary></indexterm> -<indexterm><primary>WindowBase</primary><secondary>getText</secondary></indexterm> +<indexterm><primary>getText</primary><secondary>WindowBase class</secondary></indexterm> +<indexterm><primary>WindowBase class</primary><secondary>getText</secondary></indexterm> <indexterm><primary>dialog object</primary><secondary>getText</secondary></indexterm> <indexterm><primary>dialog control object</primary><secondary>getText</secondary></indexterm> <programlisting> @@ -2311,8 +2311,8 @@ When a window is marked invisible, the operating system will not draw or redraw the window. It will only draw or redraw the area the window covered. For example if the window is part of another window's client area, and the client area is redrawn, then the window marked as invisible is not drawn. There are several methods that - the programmer can use to cause a window to be redrawn, <xref linkend="mthUpdate"/>), - <xref linkend="mthDraw"/>, etc.. + the programmer can use to cause a window to be redrawn, <xref linkend="mthUpdateClsWindowBase"/>, + <xref linkend="mthDraw"/>, etc.. </para> <para> To restate this for clarity, when the window is marked invisible, having the window update or redraw itself will do @@ -3916,8 +3916,8 @@ the user has entered, etc.. </para> <para> - The <emphasis role="italic">setText</emphasis>, <xref linkend="mthSetTitle"/>, and <xref linkend="mthTitleEquals"/> - methods do exactly the same thing. The methods are interchangeable. + The <emphasis role="italic">setText</emphasis>, <xref linkend="mthSetTitleClsWindowBase"/>, and <xref + linkend="mthTitleEquals"/> methods do exactly the same thing. The methods are interchangeable. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> @@ -3936,9 +3936,9 @@ </variablelist> </section> <!-- End WindowBase::setText() --> -<section id="mthSetTitle" xreflabel="setTitle"><title>setTitle</title> -<indexterm><primary>title=</primary></indexterm> -<indexterm><primary>WindowBase</primary><secondary>setTitle</secondary></indexterm> +<section id="mthSetTitleClsWindowBase" xreflabel="setTitle"><title>setTitle</title> +<indexterm><primary>setTitle</primary><secondary>WindowBase class</secondary></indexterm> +<indexterm><primary>WindowBase class</primary><secondary>setTitle</secondary></indexterm> <indexterm><primary>dialog object</primary><secondary>setTitle</secondary></indexterm> <indexterm><primary>dialog control object</primary><secondary>setTitle</secondary></indexterm> <programlisting> @@ -4364,7 +4364,7 @@ <para> When a window is marked visible, the operating system does not redraw the window until necessary. For example if the window is covered by another window and then uncovered. There are several methods that the programmer can use to - cause a window to be redrawn, <xref linkend="mthUpdate"/>), <xref linkend="mthDraw"/>, etc.. + cause a window to be redrawn, <xref linkend="mthUpdateClsWindowBase"/>), <xref linkend="mthDraw"/>, etc.. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> @@ -4694,9 +4694,9 @@ </para> </section> -<section id="mthUpdate" xreflabel="update"><title>update</title> -<indexterm><primary>update</primary></indexterm> -<indexterm><primary>WindowBase</primary><secondary>update</secondary></indexterm> +<section id="mthUpdateClsWindowBase" xreflabel="update"><title>update</title> +<indexterm><primary>update</primary><secondary>WindowBase class</secondary></indexterm> +<indexterm><primary>WindowBase class</primary><secondary>update</secondary></indexterm> <indexterm><primary>dialog object</primary><secondary>update</secondary></indexterm> <indexterm><primary>dialog control object</primary><secondary>update</secondary></indexterm> <programlisting> Modified: docs/trunk/oodialog/en-US/windowBaseDCO.xml =================================================================== --- docs/trunk/oodialog/en-US/windowBaseDCO.xml 2012-11-21 01:14:33 UTC (rev 8607) +++ docs/trunk/oodialog/en-US/windowBaseDCO.xml 2012-11-21 01:33:11 UTC (rev 8608) @@ -507,7 +507,7 @@ <section id="wbdcoSetTitle" xreflabel="setTitle"><title>setTitle</title> <programlisting> -WindowBase::<xref linkend="mthSetTitle"/> +WindowBase::<xref linkend="mthSetTitleClsWindowBase"/> <![CDATA[ >>--setTitle(--newText--)------------------------>< @@ -610,7 +610,7 @@ <section id="wbdcoUpdate" xreflabel="update"><title>update</title> <programlisting> -WindowBase::<xref linkend="mthUpdate"/> +WindowBase::<xref linkend="mthUpdateClsWindowBase"/> <![CDATA[ >>--update--------------------------------------->< Modified: docs/trunk/oodialog/en-US/windowBaseDO.xml =================================================================== --- docs/trunk/oodialog/en-US/windowBaseDO.xml 2012-11-21 01:14:33 UTC (rev 8607) +++ docs/trunk/oodialog/en-US/windowBaseDO.xml 2012-11-21 01:33:11 UTC (rev 8608) @@ -508,7 +508,7 @@ <section id="wbdoSetTitle" xreflabel="setTitle"><title>setTitle</title> <programlisting> -WindowBase::<xref linkend="mthSetTitle"/> +WindowBase::<xref linkend="mthSetTitleClsWindowBase"/> <![CDATA[ >>--setTitle(--newText--)------------------------>< @@ -600,7 +600,7 @@ <section id="wbdoUpdate" xreflabel="update"><title>update</title> <programlisting> -WindowBase::<xref linkend="mthUpdate"/> +WindowBase::<xref linkend="mthUpdateClsWindowBase"/> <![CDATA[ >>--update--------------------------------------->< |
From: <mie...@us...> - 2012-11-22 04:46:58
|
Revision: 8612 http://sourceforge.net/p/oorexx/code-0/8612 Author: miesfeld Date: 2012-11-22 04:46:55 +0000 (Thu, 22 Nov 2012) Log Message: ----------- #419 Add Tooltip control See ticket [Feature-Requests:#419] Modified Paths: -------------- docs/trunk/oodialog/en-US/dialogObject.xml docs/trunk/oodialog/en-US/edit.xml docs/trunk/oodialog/en-US/eventNotification.xml docs/trunk/oodialog/en-US/tooltip.xml Modified: docs/trunk/oodialog/en-US/dialogObject.xml =================================================================== --- docs/trunk/oodialog/en-US/dialogObject.xml 2012-11-22 03:45:07 UTC (rev 8611) +++ docs/trunk/oodialog/en-US/dialogObject.xml 2012-11-22 04:46:55 UTC (rev 8612) @@ -435,12 +435,16 @@ <entry>Returns a handle to a logical font, the implementation is <emphasis role="bold">incorrect</emphasis>.</entry> </row> <row> +<entry><xref linkend="wedoCreateFontEx"/></entry> +<entry>Retrieves a handle to a logical font from the system font manager</entry> +</row> +<row> <entry><xref linkend="wedoCreatePen"/></entry> <entry>Creates a logical pen that has the specified style, width, and color.</entry> </row> <row> -<entry><xref linkend="wedoCreateFontEx"/></entry> -<entry>Retrieves a handle to a logical font from the system font manager</entry> +<entry><xref linkend="createToolTip"/></entry> +<entry>Creates the underlying Windows ToolTip control and returns an instantiated Rexx <xref linkend="clsToolTip"/> object.</entry> </row> <row> <entry><xref linkend="enDefListDragHandler"/></entry> @@ -3102,6 +3106,151 @@ dialog has been created. For any error, all the methods return the <emphasis role="italic">.nil</emphasis> object. </para> + +<section id="mthCreateToolTip" xreflabel="createToolTip"><title>createToolTip</title> +<indexterm><primary>createToolTip</primary></indexterm> +<indexterm><primary>dialog object</primary><secondary>createToolTip</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--createToolTip(--id--+----------+--)------------->< + +-,-style--+ +]]> +</programlisting> + +<para> + Creates the underlying Windows ToolTip control and returns an instantiated Rexx <xref linkend="clsToolTip"/> object. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The arguments are: + </para> + <variablelist> + <varlistentry><term>id [required]</term> + <listitem> + <para> + The resource ID of the ToolTip dialog control. May be numeric or <xref linkend="defSymbolicId"/>. + </para> + </listitem></varlistentry> + <varlistentry><term>style [optional]</term> + <listitem> + <para> + A list of 0 or more of the following keywords separated by spaces, case is not significant. If this argument is + omitted, the default style is set to NOPREFIX ALWAYSTIP: + </para> + <para> + <simplelist type='vert' columns='3'> + <member>ALWAYSTIP </member> + <member>BALLOON </member> + <member>CLOSE </member> + <member>NOANIMATE </member> + <member>NOFADE </member> + <member>NOPREFIX </member> + <member>USEVISUALSTYLE</member> + </simplelist> + <variablelist> + <varlistentry><term>ALWAYSTIP</term> + <listitem> + <para> + Indicates that the ToolTip control appears when the cursor is on a tool, even if the ToolTip control's owner + window is inactive. Without this style, the ToolTip appears only when the tool's owner window is active. + </para> + </listitem></varlistentry> + <varlistentry><term>BALLOON</term> + <listitem> + <para> + Indicates that the ToolTip control has the appearance of a cartoon <emphasis role="italic">balloon</emphasis>, + with rounded corners and a stem pointing to the item. + </para> + </listitem></varlistentry> + <varlistentry><term>CLOSE</term> + <listitem> + <para> + Displays a Close button on the ToolTip. + </para> + </listitem></varlistentry> + <varlistentry><term>NOANIMATE</term> + <listitem> + <para> + Disables sliding ToolTip animation on Microsoft Windows 2000 systems. + </para> + </listitem></varlistentry> + <varlistentry><term>NOFADE</term> + <listitem> + <para> + Disables fading ToolTip animation on Windows 2000 systems. + </para> + </listitem></varlistentry> + <varlistentry><term>NOPREFIX</term> + <listitem> + <para> + Prevents the system from stripping the ampersand character from a string. Without this style, the system + automatically strips ampersand characters. This allows an application to use the same string as both a menu item + and as text in a ToolTip control. + </para> + </listitem></varlistentry> + <varlistentry><term>USEVISUALSTYLE</term> + <listitem> + <para> + Uses themed hyperlinks. The theme will define the styles for any links in the tooltip. This style always requires + <xref linkend="kywToolTipPARSELINKS"/> to be set. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + Returns an instantiated Rexx <xref linkend="clsToolTip"/> object that represents the newly created Windows tool tip. On + error, the <computeroutput>.nil</computeroutput> object is returned. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + Unlike most other dialog controls, the ToolTip control can not be added to the dialog <xref + linkend="ovvDialogTemplate"/>. The <emphasis role="italic">createToolTip</emphasis> method creates the underlying ToolTip + control, and must be invoked <emphasis role="italic">after</emphasis> the Windows dialog has been created. There is no + <xref linkend="clsUserDialog"/> method to create a tool tip in the <xref linkend="mthDefineDialog"/> method. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect usage is detected. + </para> + <para> + Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. In some cases, the failure to create the + underlying ToolTip control by the operating system can be detected in the ooDialog framework. This will result in the + <computeroutput>.SystemErrorCode</computeroutput> being set. However, this type of failure is unlikely to happen. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example creates a ToolTip with the <emphasis role="italic">BALLOON</emphasis> style and a Close button. It then + gives the ToolTip a title and an icon: +<programlisting> +<![CDATA[ +::method initDialog + expose icon + + toolTip = self~createToolTip(IDC_TT_BALLOON, 'BALLOON CLOSE') + toolTip~setTitle("Important Message", icon) + ... + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End dialog object::createToolTip() --> + + <section id="mthNewCheckBox" xreflabel="newCheckBox"><title>newCheckBox</title> <indexterm><primary>newCheckBox</primary></indexterm> <indexterm><primary>dialog object</primary><secondary>newCheckBox</secondary></indexterm> @@ -3870,19 +4019,19 @@ </section> -<section id="mthNewTab" xreflabel="newTab"><title>newTab</title> -<indexterm><primary>newTab</primary></indexterm> -<indexterm><primary>dialog object</primary><secondary>newTab</secondary></indexterm> +<section id="mthNewStatic" xreflabel="newStatic"><title>newStatic</title> +<indexterm><primary>newStatic</primary></indexterm> +<indexterm><primary>dialog object</primary><secondary>newStatic</secondary></indexterm> <programlisting> <![CDATA[ ->>--newTab(--id--)------------------------------->< +>>--newStatic(--id--)---------------------------->< ]]> </programlisting> <para> - The <emphasis role="italic">newTab</emphasis> method returns an object of the - <xref linkend="clsTab"/> control class. This object represents the tab control in the underlying dialog + The <emphasis role="italic">newStatic</emphasis> method returns an object of the + <xref linkend="clsStatic"/> control class. This object represents the static control in the underlying dialog with the specified resource ID. </para> <variablelist> @@ -3890,174 +4039,197 @@ <listitem> <para> The single argument is: - </para> <variablelist> <varlistentry><term>id [required]</term> <listitem> <para> - The resource ID of the tab dialog control. May be numeric or <xref linkend="defSymbolicId"/>. + The resource ID of the static dialog control. May be numeric or <xref linkend="defSymbolicId"/>. </para> </listitem></varlistentry> </variablelist> + </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - An object of the tab control class or <emphasis role="italic">.nil</emphasis> on any error. + An object of the static control class or <emphasis role="italic">.nil</emphasis> on any error. </para> </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + Often static controls are give a resource ID of -1 because they do not usually need to be changed after the + underlying dialog is created. However, if the programmer needs to manipulate a static control in any way, then the + control has to have a positive resource ID. + </para> + </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - The following example initializes the tab control with symbolic ID IDC_TAB to have 5 tabs: + The following example gets a new static control object that represents the static control in the underlying dialog + with the symbolic ID of IDC_ST_NAME. Provided the underlying dialog control exists, it is resized and its text, + background color, and foreground color is changed: -<programlisting> -<![CDATA[ -::class 'MyDlgClass' subclass ResDialog + <programlisting> + <![CDATA[ + ::class 'MyDlgClass' subclass RcDialog -::method initDialog - self~newTab(IDC_TAB)~addSequence("Design", "Implementation", - - "Test", "Review", "Release") - -]]> -</programlisting> + ::method reArrange + di = self~newStatic(IDC_ST_NAME) + if di == .nil then return + di~setRect(.Rect~new(0, 0, 100, 25), "NOMOVE HIDE") + di~setText("Processing layout update!") + di~setColor(7,4) + di~show + ... + ]]> + </programlisting> </para> </listitem></varlistentry> </variablelist> </section> -<section id="mthNewToolTip" xreflabel="newToolTip"><title>newToolTip</title> -<indexterm><primary>newToolTip</primary></indexterm> -<indexterm><primary>dialog object class</primary><secondary>newToolTip</secondary></indexterm> +<section id="mthNewTab" xreflabel="newTab"><title>newTab</title> +<indexterm><primary>newTab</primary></indexterm> +<indexterm><primary>dialog object</primary><secondary>newTab</secondary></indexterm> <programlisting> <![CDATA[ ->>--newToolTip(--+--------+--)--------------------------------------------->< - +--type--+ +>>--newTab(--id--)------------------------------->< + ]]> </programlisting> <para> - xx + The <emphasis role="italic">newTab</emphasis> method returns an object of the + <xref linkend="clsTab"/> control class. This object represents the tab control in the underlying dialog + with the specified resource ID. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The arguments are: + The single argument is: </para> - <variablelist> - <varlistentry><term>TERM</term> - <listitem> - <para> - xx - </para> - </listitem></varlistentry> - </variablelist> + <variablelist> + <varlistentry><term>id [required]</term> + <listitem> + <para> + The resource ID of the tab dialog control. May be numeric or <xref linkend="defSymbolicId"/>. + </para> + </listitem></varlistentry> + </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + An object of the tab control class or <emphasis role="italic">.nil</emphasis> on any error. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> - <listitem> - <para> - Additional comments. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details</emphasis></term> - <listitem> - <para> - Raises syntax errors when incorrect usage is detected. - </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> - </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + The following example initializes the tab control with symbolic ID IDC_TAB to have 5 tabs: + <programlisting> <![CDATA[ +::class 'MyDlgClass' subclass ResDialog +::method initDialog + self~newTab(IDC_TAB)~addSequence("Design", "Implementation", - + "Test", "Review", "Release") + ]]> </programlisting> </para> </listitem></varlistentry> </variablelist> -</section> <!-- End dialog object::newToolTip() --> +</section> -<section id="mthNewStatic" xreflabel="newStatic"><title>newStatic</title> -<indexterm><primary>newStatic</primary></indexterm> -<indexterm><primary>dialog object</primary><secondary>newStatic</secondary></indexterm> +<section id="mthNewToolTip" xreflabel="newToolTip"><title>newToolTip</title> +<indexterm><primary>newToolTip</primary></indexterm> +<indexterm><primary>dialog object</primary><secondary>newToolTip</secondary></indexterm> <programlisting> <![CDATA[ ->>--newStatic(--id--)---------------------------->< - +>>--newToolTip(--id--)--------------------------->< ]]> </programlisting> <para> - The <emphasis role="italic">newStatic</emphasis> method returns an object of the - <xref linkend="clsStatic"/> control class. This object represents the static control in the underlying dialog - with the specified resource ID. + The <emphasis role="italic">newToolTip</emphasis> method returns an object of the <xref linkend="clsToolTip"/> class. This + object represents the ToolTip control in the underlying dialog with the specified resource ID. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> The single argument is: + </para> <variablelist> <varlistentry><term>id [required]</term> <listitem> <para> - The resource ID of the static dialog control. May be numeric or <xref linkend="defSymbolicId"/>. + The resource ID of the ToolTip dialog control. May be numeric or <xref linkend="defSymbolicId"/>. </para> </listitem></varlistentry> </variablelist> - </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - An object of the static control class or <emphasis role="italic">.nil</emphasis> on any error. + Returns the Rexx ToolTip object that represents the Windows ToolTip control with the sepcified resource ID, or the + <computeroutput>.nil</computeroutput> object on any error </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Often static controls are give a resource ID of -1 because they do not usually need to be changed after the - underlying dialog is created. However, if the programmer needs to manipulate a static control in any way, then the - control has to have a positive resource ID. + The <emphasis role="italic">newToolTip</emphasis> method can not be invoked until the underlying ToolTip control has been + created using the <xref linkend="mthCreateToolTip"/> method. </para> + <para> + There is only one Rexx object created for each single Windows dialog control. Once the <emphasis + role="italic">createToolTip</emphasis> method has created the underlying ToolTip, each invocation of the <emphasis + role="italic">newToolTip</emphasis> method, using the same resource ID, will return the same Rexx object. + </para> </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect usage is detected. + </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - The following example gets a new static control object that represents the static control in the underlying dialog - with the symbolic ID of IDC_ST_NAME. Provided the underlying dialog control exists, it is resized and its text, - background color, and foreground color is changed: + This example creates a balloon ToolTip that displays an important message. The message is different during different + states of the application. When the message text needs to be changed, the updateMsg() method uses the <emphasis + role="italic">newToolTip</emphasis> method to get the Rexx object representing the underlying ToolTip and changes the + text for the message: +<programlisting> +<![CDATA[ +::method initDialog + expose icon - <programlisting> - <![CDATA[ - ::class 'MyDlgClass' subclass RcDialog + toolTip = self~createToolTip(IDC_TT_BALLOON, 'BALLOON') + toolTip~setTitle("Important Message", icon) + ... - ::method reArrange - di = self~newStatic(IDC_ST_NAME) - if di == .nil then return - di~setRect(.Rect~new(0, 0, 100, 25), "NOMOVE HIDE") - di~setText("Processing layout update!") - di~setColor(7,4) - di~show - ... - ]]> - </programlisting> + +::method updateMsg private + use strict arg newMsg + + toolInfo = .ToolInfo~forID(self~newEdit(IDC_EDIT)) + toolInfo~text = newMsg + + tt = self~newToolTip(IDC_TT_BALLOON) + tt~updateTipText(toolInfo) + + +]]> +</programlisting> </para> </listitem></varlistentry> </variablelist> -</section> +</section> <!-- End dialog object::newToolTip() --> <section id="mthNewTrackBar" xreflabel="newTrackBar"><title>newTrackBar</title> <indexterm><primary>newTrackBar</primary></indexterm> Modified: docs/trunk/oodialog/en-US/edit.xml =================================================================== --- docs/trunk/oodialog/en-US/edit.xml 2012-11-22 03:45:07 UTC (rev 8611) +++ docs/trunk/oodialog/en-US/edit.xml 2012-11-22 04:46:55 UTC (rev 8612) @@ -724,9 +724,9 @@ <varlistentry><term><emphasis role="bold">Details</emphasis></term> <listitem> <para> - Requires Common Control <xref linkend="ovvComctl32"/> version 6.0 or later. If necessary use the - <xref linkend="mthComCtl32Version"/>() method to determine the current version of the library. A - syntax error is raised if this method is invoked on an operating system where it is not supported. + Requires Common Control <xref linkend="ovvComctl32"/> version 6.0 or later. If necessary use the <xref + linkend="mthComCtl32Version"/> method to determine the current version of the library. A syntax error is raised if this + method is invoked on an operating system where it is not supported. </para> <para> Raises syntax errors when incorrect arguments are detected. @@ -3164,7 +3164,7 @@ </para> <para> Requires Common Control <xref linkend="ovvComctl32"/> version 6.0 or later. If necessary use the - <xref linkend="mthComCtl32Version"/>() method to determine the current version of the library. A + <xref linkend="mthComCtl32Version"/>() method to determine the current version of the library. A syntax error is raised if this method is invoked on an operating system where it is not supported. </para> </listitem></varlistentry> Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-22 03:45:07 UTC (rev 8611) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-22 04:46:55 UTC (rev 8612) @@ -7442,8 +7442,8 @@ </programlisting> <para> - The <emphasis role="italic">connectUpDownEvent</emphasis> method connects an <xref linkend="ovvEvents"/> - notification message from a <xref linkend="clsUpDown"/> control to a method in the Rexx dialog. + 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. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -7454,7 +7454,7 @@ <varlistentry><term>id [required]</term> <listitem> <para> - The resource ID of the up-down control whose notification message is to be connected to a Rexx dialog's method. + The resource ID of the tool tip control whose notification message is to be connected to a Rexx dialog's method. May be numeric or <xref linkend="defSymbolicId"/>. </para> </listitem></varlistentry> @@ -7462,32 +7462,73 @@ <listitem> <para> Exactly one of the following keywords. The keyword specifies the event to be connected and case is not - significant. Unlike most controls, the up-down control only has one event notification. + significant. </para> <variablelist> - <varlistentry><term>DELTAPOS</term> + <varlistentry><term>LINKCLICK</term> <listitem> <para> - Sent when the position of the control is about to change. This happens when the user requests a change in the - value by pressing the control's up or down arrow. The event handler must - <link linkend="sctCodingEventHandlers">return</link> a reply for this event. The interpreter waits for that reply. + Requires Common Control <xref linkend="ovvComctl32"/> version 6.0 or later. </para> <para> - The DELTAPOS notification is sent before the scroll message which actually changes the control's position. - This allows the programmer to examine, allow, modify, or disallow the change in position. + This notification is sent when a text link inside a balloon ToolTip is clicked. This is an example of when this + notification is sent. Assume that the balloon ToolTip contains the following text: + +<programlisting> +<![CDATA[ + "This is a <A>link</A>". +]]> +</programlisting> + + When <emphasis role="italic">link</emphasis> is clicked, the LINKCLICK notification is sent. </para> </listitem></varlistentry> + <varlistentry id="kywToolTipNEEDTEXT" xreflabel="NEEDTEXT"><term>NEEDTEXT</term> + <listitem> + <para> + This notification is sent when the ToolTip control needs to retrieve the text used to display a ToolTip window. + </para> + </listitem></varlistentry> + <varlistentry><term>POP</term> + <listitem> + <para> + This notification is sent when a ToolTip is about to be hidden. + </para> + </listitem></varlistentry> + <varlistentry id="kywToolTipSHOW" xreflabel="SHOW"><term>SHOW</term> + <listitem> + <para> + This notification is sent when a ToolTip control is about to be displayed. + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term>methodName [optional]</term> <listitem> <para> - The name of the method that is to be invoked whenever the specified notification is received from the up-down - control. The programmer defines this method. If this argument is omitted, a method name is automatically - generated that consists of the event keyword preceded by <computeroutput>on</computeroutput>. For instance, - <computeroutput>onDeltaPos</computeroutput>. The method name can not be the empty string. + The name of the method that is to be invoked whenever the specified notification is received from the tool tip + control. The programmer defines this method. If this argument is omitted, a method name is automatically generated + that consists of the event keyword preceded by <computeroutput>on</computeroutput>. For instance, + <computeroutput>onNeedText</computeroutput>. The method name can not be the empty string. The empty string is treated + as an omitted argument. </para> </listitem></varlistentry> + <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, for some of the ToolTip events. + The default is <computeroutput>.true</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. + </para> + <para> + For the SHOW and NEEDTEXT events, the <emphasis role="italic">willReply</emphasis> argument is ignored. The event + handler for those events must always return a value. For the POP and PARSELINKS events, the <emphasis + role="italic">willReply</emphasis> argument can be used to specify whether the interpreter requires a reply from the + event handler or not. + </para> + </listitem></varlistentry> </variablelist> </para> </listitem></varlistentry> @@ -7516,118 +7557,308 @@ connected event happens. </para> <para> - The underlying dialog receives the UDN_* messages as the notifications for the up-down events. + The underlying dialog receives the TTN_* messages as the notifications for the tool tip events. </para> </listitem></varlistentry> </variablelist> -<section id="evtToolTipSHOW" xreflabel="SHOW"><title>Show Event Handler</title> -<indexterm><primary>ToolTip class</primary><secondary>events</secondary><tertiary>SHOW</tertiary></indexterm> +<section id="evtToolTipLINKCLICK" xreflabel="LINKCLICK"><title>LinkClick Event Handler</title> +<indexterm><primary>ToolTip class</primary><secondary>events</secondary><tertiary>LINKCLICK</tertiary></indexterm> +<para> + The event handler for the LINKCLICK event is invoked when the text link inside a Balloon ToolTip is clicked. +</para> +<para> + By default, the interpreter waits for the return from the event handler for this event and the event handler must return a + value. The actual value of the return has no meeting. This behaviour can be changed through the <emphasis + role="italic">willReply</emphasis> argument to the <xref linkend="mthConnectToolTipEvent"/> method. If <emphasis + role="italic">willReply</emphasis> is false, the interpreter does not wait for the return. +</para> <programlisting> <![CDATA[ -::method onShow unguarded - use arg what +::method onLinkClick unguarded + use arg rxToolID, rxToolTip - return what + return 0 ]]> </programlisting> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method receives two arguments: + </para> + <variablelist> + <varlistentry><term>rxToolID</term> + <listitem> + <para> + The Rexx object used as the second part of the tool <link linkend="sctToolIdentification">identification</link> the + operating system uses. This can be the Rexx dialog control object or the numeric ID that identifies the tool. + </para> + </listitem></varlistentry> + <varlistentry><term>rxToolTip</term> + <listitem> + <para> + The Rexx tool tip object. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + The actual value of the return has no meaning. 0 makes a good return. + </para> + </listitem></varlistentry> +</variablelist> + +</section> <!-- End LinkClick Event Handler --> + + +<section id="evtToolTipNEEDTEXT" xreflabel="NEEDTEXT"><title>NeedText Event Handler</title> +<indexterm><primary>ToolTip class</primary><secondary>events</secondary><tertiary>NEEDTEXT</tertiary></indexterm> <para> - The event handler for the up-down DELTAPOS event is invoked when when the position of the control is about to change. - The arguments the event handler receives allow the programmer to examine the proposed change in position, to modify - the change, or to cancel the change all together. + The event handler for the xx xx event is invoked when ... </para> <para> - The programmer must return a value from the event handler and the interpreter waits for this return. The - <xref linkend="mthDeltaPosReply"/> class method of the <xref linkend="clsUpDown"/> class is - used to properly construct the return value from the event handler. + The programmer must return xx and the interpreter waits (does not wait) for this return. </para> + +<programlisting> +<![CDATA[ +::method onNeedText unguarded + use arg x, y, z + + return zz +]]> +</programlisting> + <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The event handling method receives four arguments: + The event handling method recieves xx arguments: </para> <variablelist> - <varlistentry><term>pos</term> + <varlistentry><term>arg</term> <listitem> <para> - A signed whole number that contains the up-down control's current position. + xx </para> </listitem></varlistentry> - <varlistentry><term>delta</term> + <varlistentry><term>arg1</term> <listitem> <para> - A signed whole number that contains the proposed change in the up-down control's position. This is positive if the - user has clicked the up button or used the up arrow key. If the user has clicked the down button or used the down - arrow key, this number will be negative. + xx </para> </listitem></varlistentry> - <varlistentry><term>id</term> + <varlistentry><term>arg2</term> <listitem> <para> - The resource ID of the up-down control whose position is about to change. + xx </para> </listitem></varlistentry> - <varlistentry><term>hwnd</term> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + xx + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example</emphasis></term> + <listitem> + <para> + The following example ... + +<programlisting> +<![CDATA[ + + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> + +</section> <!-- End NeedText Event Handler --> + + +<section id="evtToolTipPOP" xreflabel="POP"><title>Pop Event Handler</title> +<indexterm><primary>ToolTip class</primary><secondary>events</secondary><tertiary>POP</tertiary></indexterm> +<para> + The event handler for the xx xx event is invoked when ... +</para> +<para> + The programmer must return xx and the interpreter waits (does not wait) for this return. +</para> + +<programlisting> +<![CDATA[ +::method onPop unguarded + use arg x, y, z + + return zz +]]> +</programlisting> + +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method recieves xx arguments: + </para> + <variablelist> + <varlistentry><term>arg</term> <listitem> <para> - The window <xref linkend="defHandle"/> of the up-down control whose position is about to change. + xx </para> </listitem></varlistentry> + <varlistentry><term>arg1</term> + <listitem> + <para> + xx + </para> + </listitem></varlistentry> + <varlistentry><term>arg2</term> + <listitem> + <para> + xx + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return:</emphasis></term> <listitem> <para> - A delta position buffer must be returned by the event handler. This buffer can only be constructed properly by - using the <xref linkend="clsUpDown"/> class's <xref linkend="mthDeltaPosReply"/> - method. The arguments to <emphasis role="italic">deltaPosReply</emphasis> allow the programmer to return a value - that makes no change to the new position, cancels altogether the change in position, or modifies the resulting new - position. + xx </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example</emphasis></term> <listitem> <para> - The following example examines the change in position in the up-down control and modifies it so that the position in - the up-down control is always an even number. Note that the <emphasis role="italic">deltaPosReply</emphasis> method - ignores the second and third arguments when the first argument is <computeroutput>.false</computeroutput>. So, in - the code below, if <emphasis role="italic">change</emphasis> remains <computeroutput>.false</computeroutput>, then - the values of <emphasis role="italic">cancel</emphasis> and <emphasis role="italic">delta</emphasis> do not matter. + The following example ... <programlisting> <![CDATA[ -::method initDialog -... - self~connectUpDownEvent(IDC_UPD, "DELTAPOS", onPosChange) -... -::method onPosChange unguarded - use arg pos, delta, id, hwnd +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> - change = .false - cancel = .false +</section> <!-- End Pop Event Handler --> - if ((pos + delta) // 2) <> 0 then do - change = .true - if delta > 0 then delta += 1 - else delta -= 1 + +<section id="evtToolTipSHOW" xreflabel="SHOW"><title>Show Event Handler</title> +<indexterm><primary>ToolTip class</primary><secondary>events</secondary><tertiary>SHOW</tertiary></indexterm> + +<programlisting> +<![CDATA[ +::method onShow unguarded + use arg rxToolID, rxToolTip + + return trueOrFalse +]]> +</programlisting> + +<para> + The event handler for the tool tip SHOW event is invoked when the ToolTip is about to display its window. +</para> +<para> + The programmer must alwayse return a value from the event handler and the interpreter waits for this return. The <emphasis + role="italic">willReply</emphasis> argument of the <xref linkend="mthConnectToolTipEvent"/> method is ignored for this + event. If the programmer does not intend to return a value from the event handler, the event should not be connected. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method receives two arguments: + </para> + <variablelist> + <varlistentry><term>rxToolID</term> + <listitem> + <para> + The Rexx object used as the second part of the tool <link linkend="sctToolIdentification">identification</link> the + operating system uses. This can be the Rexx dialog control object or the numeric ID that identifies the tool. + </para> + </listitem></varlistentry> + <varlistentry><term>rxToolTip</term> + <listitem> + <para> + The Rexx tool tip object. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + To display the ToolTip in its default position, return false. To customize the position, reposition the window and return + true. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + Writing an event handler for the SHOW event gives the programmer the opportunity to customize the position of the + ToolTip. Within the event handler, calculate the desired position of the ToolTip, then use the <xref + linkend="mthSetWindowPos"/> to place the ToolTip window in that position. The event handler needs to return true to + inform the ToolTip that custom positioning has been performed. Note that MSDN says that only the position of the window + should be changed and that trying to change the size of the window will produce unpredictable results. + </para> + <para> + A ToolTip's window rectangle is somewhat larger than its text display rectangle, and its origin is offset up and to the + left. If the application needs to accurately position the text display rectangle of a ToolTip, use the <xref + linkend="mthAdjustRect"/> mehtod converts a text display rectangle into the corresponding ToolTip window rectangle and + vice versa. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + The following example uses the ToolTip ID to determine which ToolTip tool is about to display. It then caclulates the + position the ToolTip should be shown at, and uses <emphasis role="italic">setWindowPos</emphasis> to position the window + at the point calculated. Finally, true is returned, so the ToolTip knows not to position itself at its default position: + +<programlisting> +<![CDATA[ + +::method onShow unguarded + expose clRect1 clRect2 clRect3 clRect4 + use arg toolID, toolTip + + select + when toolID == .constDir[IDTOOL_DLG_RECT1] then pos = .Point~new(clRect1~left, clRect1~top) + when toolID == .constDir[IDTOOL_DLG_RECT2] then pos = .Point~new(clRect2~left, clRect2~top) + when toolID == .constDir[IDTOOL_DLG_RECT3] then pos = .Point~new(clRect3~left, clRect3~top) + when toolID == .constDir[IDTOOL_DLG_RECT4] then pos = .Point~new(clRect4~left, clRect4~top) + otherwise pos = .Point~new end + -- End select - return .UpDown~deltaPosReply(change, cancel, delta) + self~client2screen(pos) + toolTip~setWindowPos(TOPMOST, pos, .Size~new(0, 0), "NOACTIVATE NOSIZE NOZORDER") + return .true + + ]]> </programlisting> </para> </listitem></varlistentry> </variablelist> -</section> <!-- End Sjpw Event Handler --> +</section> <!-- End ToolTip SHOW Event Handler --> + + </section> <!-- End EventNotification::connectToolTipEvent() --> Modified: docs/trunk/oodialog/en-US/tooltip.xml =================================================================== --- docs/trunk/oodialog/en-US/tooltip.xml 2012-11-22 03:45:07 UTC (rev 8611) +++ docs/trunk/oodialog/en-US/tooltip.xml 2012-11-22 04:46:55 UTC (rev 8612) @@ -213,14 +213,18 @@ <entry align="center"><emphasis role="bold">External Methods</emphasis></entry> </row> <row> -<entry><link linkend="tmthNewToolTip">newToolTip</link></entry> -<entry>Returns a <computeroutput>ToolTip</computeroutput> object for the control with the specified ID.</entry> +<entry><link linkend="tmthCreateToolTip">createToolTip</link></entry> +<entry>Creates the underlying Windows ToolTip control and returns an instantiated Rexx <xref linkend="clsToolTip"/> object.</entry> </row> <row> <entry><link linkend="tmthConnectToolTipEvent">connectToolTipEvent</link></entry> <entry>Connects tool tip event notifications to a method in the Rexx dialog object</entry> </row> <row> +<entry><link linkend="tmthNewToolTip">newToolTip</link></entry> +<entry>Returns the Rexx <computeroutput>ToolTip</computeroutput> object for the tool tip control with the specified ID.</entry> +</row> +<row> <entry align="center"><emphasis role="bold">Instance Methods</emphasis></entry> <entry align="center"><emphasis role="bold">Instance Methods</emphasis></entry> </row> @@ -373,21 +377,6 @@ </section> -<section id="tmthNewToolTip"><title>newToolTip (dialog object method)</title> -<para> - ToolTip objects can not be instantiated by the programmer from Rexx code. Rather an ToolTip object is obtained - by using the <link linkend="mthNewToolTip">newToolTip</link>() method of the dialog <link - linkend="chpDialogObject">object</link>. The syntax is: -<programlisting> -<![CDATA[ ->>-newToolTip(--id--)--------------------->< - -]]> -</programlisting> -</para> -</section> <!-- End newToolTip() [PlainBaseDialog method] --> - - <section id="tmthConnectToolTipEvent"><title>connectToolTipEvent (dialog object method)</title> <para> To connect event notifications from an tool tip control use the <link @@ -404,6 +393,38 @@ </section> <!-- End connectToolTipEvent() [EventNotification method] --> +<section id="tmthCreateToolTip"><title>createToolTip (dialog object method)</title> +<para> + To create the underlying Windows ToolTip control use the <link linkend="mthCreateToolTip">createToolTip</link> method of + the <link linkend="chpDialogObject">dialog</link> object. This method always returns the instantiated Rexx object that + represents the created tool tip control. The basic syntax is: + +<programlisting> +<![CDATA[ +>>--createToolTip(--id--+----------+--)------------->< + +-,-style--+ +]]> +</programlisting> +</para> +</section> <!-- End createToolTipt() [PlainBaseDialog method] --> + + +<section id="tmthNewToolTip"><title>newToolTip (dialog object method)</title> +<para> + ToolTip objects can not be instantiated by the programmer from Rexx code. Rather a ToolTip object is obtained either by + using the <xref linkend="mthCreateToolTip"/> method or the <link linkend="mthNewToolTip">newToolTip</link> method of + the dialog <link linkend="chpDialogObject">object</link>. The syntax for the <emphasis role="italic">newToolTip</emphasis> + is: +<programlisting> +<![CDATA[ +>>-newToolTip(--id--)--------------------->< + +]]> +</programlisting> +</para> +</section> <!-- End newToolTip() [PlainBaseDialog method] --> + + <section id="mthActivate"><title>activate</title> <indexterm><primary>activate</primary></indexterm> <indexterm><primary>ToolTip class</primary><secondary>activate</secondary></indexterm> @@ -416,19 +437,19 @@ </programlisting> <para> - xx + Activates or deactivates this tool tip. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - xx + The single optional argument is: </para> <variablelist> - <varlistentry><term>TERM</term> + <varlistentry><term>activate</term> <listitem> <para> - xx + If true activates this tool it, if false deactivate this tool tip. The default if the argument is omitted is true. </para> </listitem></varlistentry> </variablelist> @@ -436,35 +457,22 @@ <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns 0, always. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + A ToolTip control can be either active or inactive. When it is active, the ToolTip text appears when the mouse pointer is + on a tool. When it is inactive, the ToolTip text does not appear, even if the pointer is on a tool. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> <listitem> <para> - Raises syntax errors when incorrect arguments are detected. + Raises syntax errors when incorrect usage is detected. </para> - <para> - xx - </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> - <listitem> - <para> - This example ... -<programlisting> -<![CDATA[ - -]]> -</programlisting> - </para> - </listitem></varlistentry> </variablelist> </section> <!-- End ToolTip::activate() --> @@ -474,13 +482,13 @@ <indexterm><primary>ToolTip class</primary><secondary>addTool</secondary></indexterm> <programlisting> <![CDATA[ ->>--addTool(--+--------+--)--------------------------------------------->< - +--type--+ +>>--addTool(--tool--+---------+--+---------+--+------------+--)---------------->< + +-,-text--+ +-,-flags-+ +-,-userData-+ ]]> </programlisting> <para> - xx + Adds a tool to this tool tip. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -489,12 +497,115 @@ The arguments are: </para> <variablelist> - <varlistentry><term>TERM</term> + <varlistentry><term>tool [required]</term> <listitem> <para> - xx + The dialog control that defines the tool being added. </para> </listitem></varlistentry> + <varlistentry><term>text [optional]</term> + <listitem> + <para> + Text for the tool. If omitted, or the empty string, or the string: TEXTCALLBACK then the tool tip sends the NEEDTEXT + notification and the program supplies the text. + </para> + <para> + The maximum length of the text is 1023 characters, which includes any possible end of line (0x0D0A) sequences. + </para> + </listitem></varlistentry> + <varlistentry><term>flags [optional]</term> + <listitem> + <para> + A list of 0 or more of the following keywords separated by spaces, case is not significant. If this argument is + omitted, the flags are set to ISISHWND SUBCLASS: + </para> + <para> + <simplelist type='vert' columns='3'> + <member>ABSOLUTE </member> + <member>CENTERTIP </member> + <member>IDISHWND </member> + <member>PARSELINKS </member> + <member>RTLREADING </member> + <member>SUBCLASS </member> + <member>TRACK </member> + <member>TRANSPARENT</member> + </simplelist> + <variablelist> + <varlistentry><term>ABSOLUTE</term> + <listitem> + <para> + Positions the ToolTip window at the same coordinates provided by the <xref linkend="mthTrackPosition"/> method. + This flag must be used with the TRACK flag. This flag is not useful for the simple case the <emphasis + role="italic">addTool</emphasis> method is designed for. + </para> + </listitem></varlistentry> + <varlistentry><term>CENTERTIP</term> + <listitem> + <para> + Centers the ToolTip window below the tool specified by the <emphasis role="italic">tool</emphasis> argument. + </para> + </listitem></varlistentry> + <varlistentry><term>IDISHWND</term> + <listitem> + <para> + Indicates that the ID part of the tool <link linkend="sctToolIdentification">identification</link> is the window + handle to the tool. If this flag is not set, the ID part is the tool's identification number. For the <emphasis + role="italic">addTool</emphasis> method, the ooDialog framework always sets this flag, it does not need to be + specified by the programmer. The window <link linkend="defHandle">handle</link> of the <emphasis + role="italic">tool</emphasis> argument is always the ID part of the tool identification. + </para> </listitem></varlistentry> + <varlistentry id="kywToolTipPARSELINKS" xreflabel="PARSELINKS"><term>PARSELINKS</term> + <listitem> + <para> + Requires Common Control <xref linkend="ovvComctl32"/> version 6.0 or later. + </para> + <para> + Indicates that links in the ToolTip text should be parsed. + </para> + </listitem></varlistentry> + <varlistentry><term>RTLREADING</term> + <listitem> + <para> + Indicates that the ToolTip text will be displayed in the opposite direction to the text in the parent window. + </para> + </listitem></varlistentry> + <varlistentry><term>SUBCLASS</term> + <listitem> + <para> + Indicates that the ToolTip control should subclass the tool's window to intercept messages, such as WM_MOUSEMOVE. + If this flag is not set, the <xref linkend="mthManageAtypicalTool"/> method must be used so the mouse messages + are forwarded to the ToolTip control. For the simple case that the <emphasis role="italic">addTool</emphasis> + method is designed for, the <emphasis role="italic">manageAtypicalTool</emphasis> method will not work. The + ooDialog framwork always sets this flag during the <emphasis role="italic">addTool</emphasis> method, the + programmer does not need to include this flag. + </para> + </listitem></varlistentry> + <varlistentry><term>TRACK</term> + <listitem> + <para> + Positions the ToolTip window next to the tool to which it corresponds and moves the window according to + coordinates supplied by the <xref linkend="mthTrackPosition"/> method. The programmer must activate this + type of tool using the <xref linkend="mthTrackActivate"/> method. This flag is not useful for the simple case + the <emphasis role="italic">addTool</emphasis> method is designed for. + </para> + </listitem></varlistentry> + <varlistentry><term>TRANSPARENT</term> + <listitem> + <para> + Causes the ToolTip control to forward mouse event messages to the parent window. This is limited to mouse events + that occur within the bounds of the ToolTip window. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term>userData [optional]</term> + <listitem> + <para> + A user data value to be associated with the tool. This can be any Rexx object the programmer wants. Note that the + value is associated with the tool, not the tool tip. + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> |
From: <mie...@us...> - 2012-11-22 19:16:18
|
Revision: 8615 http://sourceforge.net/p/oorexx/code-0/8615 Author: miesfeld Date: 2012-11-22 19:16:14 +0000 (Thu, 22 Nov 2012) Log Message: ----------- Incremental work on ooDialog doc Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml docs/trunk/oodialog/en-US/listview.xml docs/trunk/oodialog/en-US/overview.xml docs/trunk/oodialog/en-US/tooltip.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-22 04:53:36 UTC (rev 8614) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-22 19:16:14 UTC (rev 8615) @@ -7450,87 +7450,94 @@ <listitem> <para> The arguments are: + </para> + <variablelist> + <varlistentry><term>id [required]</term> + <listitem> + <para> + The resource ID of the tool tip control whose notification message is to be connected to a method in the Rexx dialog. + May be numeric or <xref linkend="defSymbolicId"/>. + </para> + </listitem></varlistentry> + <varlistentry><term>event [required]</term> + <listitem> + <para> + Exactly one of the following keywords. The keyword specifies the event to be connected. Case is not significant. + </para> + <para> + <simplelist type='vert' columns='3'> + <member>LINKCLICK</member> + <member>NEEDTEXT</member> + <member>POP</member> + <member>SHOW</member> + </simplelist> + </para> <variablelist> - <varlistentry><term>id [required]</term> + <varlistentry><term>LINKCLICK</term> <listitem> <para> - The resource ID of the tool tip control whose notification message is to be connected to a Rexx dialog's method. - May be numeric or <xref linkend="defSymbolicId"/>. + Requires Common Control <xref linkend="ovvComctl32"/> version 6.0 or later. </para> - </listitem></varlistentry> - <varlistentry><term>event [required]</term> - <listitem> <para> - Exactly one of the following keywords. The keyword specifies the event to be connected and case is not - significant. - </para> - <variablelist> - <varlistentry><term>LINKCLICK</term> - <listitem> - <para> - Requires Common Control <xref linkend="ovvComctl32"/> version 6.0 or later. - </para> - <para> - This notification is sent when a text link inside a balloon ToolTip is clicked. This is an example of when this - notification is sent. Assume that the balloon ToolTip contains the following text: + This notification is sent when a text link inside a balloon ToolTip is clicked. MSDN provides this example of when + this notification is sent. Assume that the balloon ToolTip contains the following text: <programlisting> <![CDATA[ - "This is a <A>link</A>". + "This is a <A>link</A>". ]]> </programlisting> - When <emphasis role="italic">link</emphasis> is clicked, the LINKCLICK notification is sent. - </para> - </listitem></varlistentry> - <varlistentry id="kywToolTipNEEDTEXT" xreflabel="NEEDTEXT"><term>NEEDTEXT</term> - <listitem> - <para> - This notification is sent when the ToolTip control needs to retrieve the text used to display a ToolTip window. - </para> - </listitem></varlistentry> - <varlistentry><term>POP</term> - <listitem> - <para> - This notification is sent when a ToolTip is about to be hidden. - </para> - </listitem></varlistentry> - <varlistentry id="kywToolTipSHOW" xreflabel="SHOW"><term>SHOW</term> - <listitem> - <para> - This notification is sent when a ToolTip control is about to be displayed. - </para> - </listitem></varlistentry> - </variablelist> + When <emphasis role="italic">link</emphasis> is clicked, the LINKCLICK notification is sent. + </para> </listitem></varlistentry> - <varlistentry><term>methodName [optional]</term> + <varlistentry id="kywToolTipNEEDTEXT" xreflabel="NEEDTEXT"><term>NEEDTEXT</term> <listitem> <para> - The name of the method that is to be invoked whenever the specified notification is received from the tool tip - control. The programmer defines this method. If this argument is omitted, a method name is automatically generated - that consists of the event keyword preceded by <computeroutput>on</computeroutput>. For instance, - <computeroutput>onNeedText</computeroutput>. The method name can not be the empty string. The empty string is treated - as an omitted argument. + This notification is sent when the ToolTip control needs to retrieve the text used to display a ToolTip window. </para> </listitem></varlistentry> - <varlistentry><term>willReply [optional]</term> + <varlistentry><term>POP</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, for some of the ToolTip events. - The default is <computeroutput>.true</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. + This notification is sent when a ToolTip is about to be hidden. </para> + </listitem></varlistentry> + <varlistentry id="kywToolTipSHOW" xreflabel="SHOW"><term>SHOW</term> + <listitem> <para> - For the SHOW and NEEDTEXT events, the <emphasis role="italic">willReply</emphasis> argument is ignored. The event - handler for those events must always return a value. For the POP and PARSELINKS events, the <emphasis - role="italic">willReply</emphasis> argument can be used to specify whether the interpreter requires a reply from the - event handler or not. + This notification is sent when a ToolTip control is about to be displayed. </para> </listitem></varlistentry> </variablelist> - </para> + </listitem></varlistentry> + <varlistentry><term>methodName [optional]</term> + <listitem> + <para> + The name of the method that is to be invoked whenever the specified notification is received from the tool tip + control. The programmer defines this method. If this argument is omitted, a method name is automatically generated + that consists of the event keyword preceded by <computeroutput>on</computeroutput>. For instance, + <computeroutput>onNeedText</computeroutput>. The method name can not be the empty string. The empty string is treated + as an omitted argument. + </para> + </listitem></varlistentry> + <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, for some of the ToolTip events. + The default is <computeroutput>.true</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. + </para> + <para> + For the SHOW and NEEDTEXT events, the <emphasis role="italic">willReply</emphasis> argument is ignored. The event + handler for those events must always return a value. For the POP and PARSELINKS events, the <emphasis + role="italic">willReply</emphasis> argument can be used to specify whether the interpreter requires a reply from the + event handler or not. + </para> + </listitem></varlistentry> + </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> Modified: docs/trunk/oodialog/en-US/listview.xml =================================================================== --- docs/trunk/oodialog/en-US/listview.xml 2012-11-22 04:53:36 UTC (rev 8614) +++ docs/trunk/oodialog/en-US/listview.xml 2012-11-22 19:16:14 UTC (rev 8615) @@ -56,62 +56,64 @@ Box</emphasis> control. The ooDialog <xref linkend="clsListBox"/> class provides the interface to the Windows List Box control. In general, the List-View control is more powerful than the List Box control. </para> -<para id="listControlExtendedStyles"> - List-View <emphasis role="bold">Extended Styles</emphasis>: The List-View control has been updated by Microsoft to - include a number of <emphasis role="italic">extended</emphasis> styles. These styles are similar to the styles that - can be used to create a ListView, (see the <xref linkend="mthCreateListView"/> method,) like the - <computeroutput>NOHEADER</computeroutput> or <computeroutput>SINGLESEL</computeroutput> styles. However, the way that - they are added or removed from the ListView is different. For instance, the extended styles can not be added to a - ListView at the time of creation. They can only be added after the underlying Windows control has been created. For - all practical purposes this means in the <xref linkend="mthInitDialog"/> method, or at some point in - the life cycle of the dialog after that. -</para> +<variablelist> + <varlistentry id="varListControlExtendedStyles"><term><emphasis role="bold">Extended Styles</emphasis></term> + <listitem> + <para> + The List-View control has been updated by Microsoft to include a number of <emphasis role="italic">extended</emphasis> + styles. These styles are similar to the styles that can be used to create a ListView, (see the <xref + linkend="mthCreateListView"/> method,) like the <computeroutput>NOHEADER</computeroutput> or + <computeroutput>SINGLESEL</computeroutput> styles. However, the way that they are added or removed from the ListView is + different. For instance, the extended styles can not be added to a ListView at the time of creation. They can only be + added after the underlying Windows control has been created. For all practical purposes this means in the <xref + linkend="mthInitDialog"/> method, or at some point in the life cycle of the dialog after that. + </para> + <para> + Some of the extended styles are only available on later versions of the Windows OS. As an example, the + <computeroutput>LABELTIP</computeroutput> and <computeroutput>SIMPLESELECT</computeroutput> styles are only available + on Windows XP. The documentation on the extended styles will note any requirements for each style. To work with the + extended List-View styles, use the <xref linkend="mthAddExtendedStyle"/>, the + <xref linkend="mthRemoveExtendedStyle"/>, or the + <xref linkend="mthReplaceExtendedStyle"/> methods. + </para> + <para> + There are a number of nuances to the behavior of the different extended styles on the different versions of Windows, + far too many to try and detail in this documentation. The behavior documented here is the general behavior on Windows + XP with service pack 2. + </para> + <para> + If there is a need for detailed information concerning the subtle differences in behavior on earlier versions of + Windows, the programmer should consult the Windows <xref linkend="defWindowsDoc"/>. + </para> + </listitem></varlistentry> +</variablelist> <para> - Some of the extended styles are only available on later versions of the Windows OS. As an example, the - <computeroutput>LABELTIP</computeroutput> and <computeroutput>SIMPLESELECT</computeroutput> styles are only available - on Windows XP. The documentation on the extended styles will note any requirements for each style. To work with the - extended List-View styles, use the <xref linkend="mthAddExtendedStyle"/>, the - <xref linkend="mthRemoveExtendedStyle"/>, or the - <xref linkend="mthReplaceExtendedStyle"/> methods. -</para> -<para> - There are a number of nuances to the behavior of the different extended styles on the different versions of Windows, - far too many to try and detail in this documentation. The behavior documented here is the general behavior on Windows - XP with service pack 2. -</para> -<para> - If there is a need for detailed information concerning the subtle differences in behavior on earlier versions of - Windows, the programmer should consult the Windows <xref linkend="defWindowsDoc"/>. -</para> - -<para> In addition to the methods of the class itself, the following methods from other classes in the ooDialog framework are needed, or are useful, when working with list-view controls: +</para> <variablelist> <varlistentry><term><emphasis role="bold">Instantiation:</emphasis></term> <listitem> <para> - Use the <xref linkend="mthNewListView"/> method of the - dialog <xref linkend="chpDialogObject"/> to retrieve a list-view object. + Use the <xref linkend="mthNewListView"/> method of the dialog <xref linkend="chpDialogObject"/> to retrieve a list-view + object. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Dynamic Definition:</emphasis></term> <listitem> <para> - To dynamically create a list-view in the dialog template of a <xref linkend="clsUserDialog"/> use - the <xref linkend="mthCreateListView"/> method. + To dynamically create a list-view in the dialog template of a <xref linkend="clsUserDialog"/> use the <xref + linkend="mthCreateListView"/> method. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Event Notification</emphasis></term> <listitem> <para> - To connect the <xref linkend="ovvEvents"/> notifications sent by the underlying list-view control to a - method in the Rexx dialog object use the <xref linkend="mthConnectListViewEvent"/> - method. + To connect the <xref linkend="ovvEvents"/> notifications sent by the underlying list-view control to a method in the Rexx + dialog object use the <xref linkend="mthConnectListViewEvent"/> method. </para> </listitem></varlistentry> </variablelist> -</para> <section id="sctMethodsListView"><title>Method Table</title> <para> @@ -809,7 +811,7 @@ <para> The <emphasis role="italic">addExtendedStyle</emphasis> method adds one or more of the <link - linkend="listControlExtendedStyles">extended</link> list-view styles to a list-view. These styles can not be added until + linkend="varListControlExtendedStyles">extended</link> list-view styles to a list-view. These styles can not be added until the underlying Windows list-view control has been created. They can be added in the <xref linkend="mthInitDialog"/> method, or any time thereafter. </para> @@ -2546,7 +2548,7 @@ </programlisting> <para>The <computeroutput>getExtendedStyle</computeroutput> method returns -the extended <link linkend="listControlExtendedStyles">styles</link> of a +the extended <link linkend="varListControlExtendedStyles">styles</link> of a <computeroutput>ListView</computeroutput>. The styles are returned as a string of blank delimited style keywords. These are the same keywords as those used to set the styles. @@ -2644,7 +2646,7 @@ </programlisting> <para>The <computeroutput>getExtendedStyleRaw</computeroutput> method returns -the extended <link linkend="listControlExtendedStyles">styles</link> of a +the extended <link linkend="varListControlExtendedStyles">styles</link> of a <computeroutput>ListView</computeroutput> as the numeric value of the extended style flags. This method is provided for programmers familiar with the Windows API who may wish to know, or to work with, the actual value of the @@ -5115,7 +5117,7 @@ </programlisting> <para>The <computeroutput>removeExtendedStyle</computeroutput> method removes -one or more extended <link linkend="listControlExtendedStyles">styles</link> of +one or more extended <link linkend="varListControlExtendedStyles">styles</link> of a List-View control. </para> <variablelist> @@ -5247,7 +5249,7 @@ <para>The <computeroutput>replaceExtendedStyle</computeroutput> method removes some of the List-View control's -extended <link linkend="listControlExtendedStyles">styles</link> and adds new +extended <link linkend="varListControlExtendedStyles">styles</link> and adds new extended styles. This is the equivalent of first using the <computeroutput>RemoveExtendeStyle</computeroutput> method and then using the <computeroutput>addExtendedStyle</computeroutput> method. Modified: docs/trunk/oodialog/en-US/overview.xml =================================================================== --- docs/trunk/oodialog/en-US/overview.xml 2012-11-22 04:53:36 UTC (rev 8614) +++ docs/trunk/oodialog/en-US/overview.xml 2012-11-22 19:16:14 UTC (rev 8615) @@ -969,7 +969,7 @@ <para> Each new version of the library is backwards compatible with previous versions, but, it will contain features not available in older versions. For instance, some of the List-View extended <link - linkend="listControlExtendedStyles">styles</link>) are only available with a 6.0, or later, version of the common + linkend="varListControlExtendedStyles">styles</link> are only available with a 6.0, or later, version of the common controls library. ooDialog can only provide the features available in the version of the common controls library on the system ooDialog is running on. </para> Modified: docs/trunk/oodialog/en-US/tooltip.xml =================================================================== --- docs/trunk/oodialog/en-US/tooltip.xml 2012-11-22 04:53:36 UTC (rev 8614) +++ docs/trunk/oodialog/en-US/tooltip.xml 2012-11-22 19:16:14 UTC (rev 8615) @@ -42,7 +42,7 @@ # ######################################################################### --> -<chapter id="clsToolTip"><title>ToolTip Controls</title> +<chapter id="clsToolTip" xreflabel="ToolTip"><title>ToolTip Controls</title> <indexterm><primary>ToolTip class</primary></indexterm> <para> Tooltip controls are pop-up windows that display text. Typically the text describes a <emphasis |
From: <mie...@us...> - 2012-11-22 21:57:31
|
Revision: 8616 http://sourceforge.net/p/oorexx/code-0/8616 Author: miesfeld Date: 2012-11-22 21:57:28 +0000 (Thu, 22 Nov 2012) Log Message: ----------- Incremental work on ooDialog doc Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml docs/trunk/oodialog/en-US/overview.xml docs/trunk/oodialog/en-US/tooltip.xml docs/trunk/oodialog/en-US/treeview.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-22 19:16:14 UTC (rev 8615) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-22 21:57:28 UTC (rev 8616) @@ -7514,11 +7514,10 @@ <varlistentry><term>methodName [optional]</term> <listitem> <para> - The name of the method that is to be invoked whenever the specified notification is received from the tool tip - control. The programmer defines this method. If this argument is omitted, a method name is automatically generated - that consists of the event keyword preceded by <computeroutput>on</computeroutput>. For instance, - <computeroutput>onNeedText</computeroutput>. The method name can not be the empty string. The empty string is treated - as an omitted argument. + The name of the method that is to be invoked whenever the specified event happens. The programmer defines this method. + If this argument is omitted, a method name is automatically generated that consists of the event keyword preceded by + <computeroutput>on</computeroutput>. For instance, <computeroutput>onNeedText</computeroutput>. The method name can not + be the empty string. The empty string is treated as an omitted argument. </para> </listitem></varlistentry> <varlistentry><term>willReply [optional]</term> @@ -7526,9 +7525,9 @@ <para> The <emphasis role="italic">willReply</emphasis> argument controls whether the interpreter <link linkend="sctCodingEventHandlers">waits</link> for the reply from the event handler, for some of the ToolTip events. - The default is <computeroutput>.true</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 default is <computeroutput>.true</computeroutput>, the interpreter will wait for the reply. If <emphasis + role="italic">willReply</emphasis> is <computeroutput>.false</computeroutput>, the interpreter does not wait for the + event handling method to return a value. </para> <para> For the SHOW and NEEDTEXT events, the <emphasis role="italic">willReply</emphasis> argument is ignored. The event @@ -7627,16 +7626,21 @@ <section id="evtToolTipNEEDTEXT" xreflabel="NEEDTEXT"><title>NeedText Event Handler</title> <indexterm><primary>ToolTip class</primary><secondary>events</secondary><tertiary>NEEDTEXT</tertiary></indexterm> <para> - The event handler for the xx xx event is invoked when ... + The event handler for the NEEDTEXT event is invoked when the ToolTip is about to be displayed and the ToolTip needs the + text to be displayed. When a tool is <link linkend="mthAddTool">added</link> to a ToolTip, the programmer normally supplies + a literal string to be used as the text. However, the ToolTip provides a specical value which essentially tells the ToolTip + to call back to the application when it needs the text to be displayed. The ToolTip calls back by sending the NEEDTEXT + notification. </para> <para> - The programmer must return xx and the interpreter waits (does not wait) for this return. + The programmer must return a string to be used for the text and the interpreter waits for this return. The returned text is + passed back to the ToolTip. </para> <programlisting> <![CDATA[ ::method onNeedText unguarded - use arg x, y, z + use arg return zz ]]> @@ -7646,44 +7650,151 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The event handling method recieves xx arguments: + The event handling method recieves 3 arguments: </para> <variablelist> - <varlistentry><term>arg</term> + <varlistentry><term>rxToolID</term> <listitem> <para> - xx + The Rexx object used as the second part of the tool <link linkend="sctToolIdentification">identification</link> the + operating system uses. This can be the Rexx dialog control object or the numeric ID that identifies the tool. </para> </listitem></varlistentry> - <varlistentry><term>arg1</term> + <varlistentry><term>rxToolTip</term> <listitem> <para> - xx + The Rexx tool tip object. </para> </listitem></varlistentry> - <varlistentry><term>arg2</term> + <varlistentry><term>info</term> <listitem> <para> - xx + A <computeroutput>Directory</computeroutput> object whose indexes are used to convey information concerning the event + notification to the event handler and with which the event handler returns the requested text. On invocation of the + event handler, the <computeroutput>Directory</computeroutput> object will have the following indexes with the + corresponding information: </para> + <variablelist> + <varlistentry><term><emphasis role="bold">TEXT</emphasis></term> + <listitem> + <para> + The event handler sets this index to the text to be used for the displayed ToolTip. If this index is set to the + empty string, then no ToolTip is displayed. The length of the returned text must be less than 1024 characters. The + index is set to the empty string when the <emphasis role="italic">info</emphasis> argument is passed to the event + handler. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">USERDATA</emphasis></term> + <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. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">FLAGS</emphasis></term> + <listitem> + <para> + Zero or more blank separated keywords indicating the tool's flags. The possible flag keywords are: + </para> + <para> + <simplelist type='vert' columns='3'> + <member>ABSOLUTE </member> + <member>CENTERTIP </member> + <member>IDISHWND </member> + <member>PARSELINKS </member> + <member>RTLREADING </member> + <member>SUBCLASS </member> + <member>TRACK </member> + <member>TRANSPARENT</member> + </simplelist> + <variablelist> + <varlistentry><term>ABSOLUTE</term> + <listitem> + <para> + The ToolTip window is positioned at the same coordinates provided by the <xref linkend="mthTrackPosition"/> + method. This flag must be used with the TRACK flag. + </para> + </listitem></varlistentry> + <varlistentry><term>CENTERTIP</term> + <listitem> + <para> + Indicates that the ToolTip window is centered below the tool. + </para> + </listitem></varlistentry> + <varlistentry><term>IDISHWND</term> + <listitem> + <para> + Indicates that the ID part of the tool <link linkend="sctToolIdentification">identification</link> is the window + handle to the tool. If this flag is not set, the ID part is the tool's identification number. + </para> + </listitem></varlistentry> + <varlistentry><term>PARSELINKS</term> + <listitem> + <para> + Indicates that links in the ToolTip text should be parsed. + </para> + <para> + Only available with Common Control <xref linkend="ovvComctl32"/> version 6.0 or later. + </para> + </listitem></varlistentry> + <varlistentry><term>RTLREADING</term> + <listitem> + <para> + Indicates that the ToolTip text will be displayed in the opposite direction to the text in the parent window. + </para> + </listitem></varlistentry> + <varlistentry><term>SUBCLASS</term> + <listitem> + <para> + Indicates that the ToolTip control should subclass the tool's window to intercept messages, such as WM_MOUSEMOVE. + If this flag is not set, the mouse messages must be forwarded to the ToolTip control. + </para> + </listitem></varlistentry> + <varlistentry><term>TRACK</term> + <listitem> + <para> + Positions the ToolTip window next to the tool to which it corresponds and moves the window according to + coordinates supplied by the <xref linkend="mthTrackPosition"/> method. + </para> + </listitem></varlistentry> + <varlistentry><term>TRANSPARENT</term> + <listitem> + <para> + Causes the ToolTip control to forward mouse event messages to the parent window. This is limited to mouse events + that occur within the bounds of the ToolTip window. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + </variablelist> </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return:</emphasis></term> <listitem> <para> - xx + The event handler must return true or false. When false is returned, the ToolTip continues to generate NEEDTEXT + notifications each time it is about to display the tool tip window. If true is returned, the ToolTip control stores the + information and will not request it again. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example</emphasis></term> <listitem> <para> - The following example ... + The following example shows a simple NEEDTEXT event handler that sets the tool tip text when the mouse hovers over a push + button. True is returned to indicate that the ToolTip should store the text for that tool and need not ask for it again? <programlisting> <![CDATA[ +::method onNeedText unguarded + use arg id, toolTip, info + info~text = 'Press Test to execute the regression test suite ...' + return .true + ]]> </programlisting> </para> @@ -7696,18 +7807,21 @@ <section id="evtToolTipPOP" xreflabel="POP"><title>Pop Event Handler</title> <indexterm><primary>ToolTip class</primary><secondary>events</secondary><tertiary>POP</tertiary></indexterm> <para> - The event handler for the xx xx event is invoked when ... + The event handler for the POP event is invoked when the ToolTip is about to hide a displayed tip. </para> <para> - The programmer must return xx and the interpreter waits (does not wait) for this return. + By default, the interpreter waits for the return from the event handler for this event and the event handler must return a + value. The actual value of the return has no meeting. This behaviour can be changed through the <emphasis + role="italic">willReply</emphasis> argument to the <xref linkend="mthConnectToolTipEvent"/> method. If <emphasis + role="italic">willReply</emphasis> is false, the interpreter does not wait for the return. </para> <programlisting> <![CDATA[ ::method onPop unguarded - use arg x, y, z + use arg rxToolID, rxToolTip - return zz + return 0 ]]> </programlisting> @@ -7715,48 +7829,30 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The event handling method recieves xx arguments: + The event handling method receives two arguments: </para> <variablelist> - <varlistentry><term>arg</term> + <varlistentry><term>rxToolID</term> <listitem> <para> - xx + The Rexx object used as the second part of the tool <link linkend="sctToolIdentification">identification</link> the + operating system uses. This can be the Rexx dialog control object or the numeric ID that identifies the tool. </para> </listitem></varlistentry> - <varlistentry><term>arg1</term> + <varlistentry><term>rxToolTip</term> <listitem> <para> - xx + The Rexx tool tip object. </para> </listitem></varlistentry> - <varlistentry><term>arg2</term> - <listitem> - <para> - xx - </para> - </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return:</emphasis></term> <listitem> <para> - xx + The actual value of the return has no meaning. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example</emphasis></term> - <listitem> - <para> - The following example ... - -<programlisting> -<![CDATA[ - - -]]> -</programlisting> - </para> - </listitem></varlistentry> </variablelist> </section> <!-- End Pop Event Handler --> @@ -7855,7 +7951,6 @@ return .true - ]]> </programlisting> </para> @@ -7864,8 +7959,6 @@ </section> <!-- End ToolTip SHOW Event Handler --> - - </section> <!-- End EventNotification::connectToolTipEvent() --> @@ -8254,7 +8347,7 @@ </variablelist> <section id="evtTreeViewBEGINDRAG" xreflabel="BEGINDRAG"><title>BeginDrag Event Handler</title> -<indexterm><primary>TreeView Event</primary><secondary>BEGINDRAG</secondary></indexterm> +<indexterm><primary>TreeView class</primary><secondary>events</secondary><tertiary>BEGINDRAG</tertiary></indexterm> <para> The event-handling method connected to BEGINDRAG receives three arguments: the control ID of the tree view control, the @@ -8278,7 +8371,7 @@ </section> <section id="evtTreeViewBEGINRDRAG" xreflabel="BEGINRDRAG"><title>BeginRDrag Event Handler</title> -<indexterm><primary>TreeView Event</primary><secondary>BEGINRDRAG</secondary></indexterm> +<indexterm><primary>TreeView class</primary><secondary>events</secondary><tertiary>BEGINRDRAG</tertiary></indexterm> <para> The event-handling method connected to BEGINRDRAG receives three arguments: the control ID of the tree view control, the @@ -8303,7 +8396,7 @@ <section id="evtTreeViewBEGINEDIT" xreflabel="BEGINEDIT"><title>BeginEdit Event Handler</title> -<indexterm><primary>TreeView Event</primary><secondary>BEGINEDIT</secondary></indexterm> +<indexterm><primary>TreeView class</primary><secondary>events</secondary><tertiary>BEGINEDIT</tertiary></indexterm> <para> The event handler for the BEGINEDIT event is invoked when the user begins a label editing operation on an item of the tree-view. When label editing begins, an edit control is created by the operating systm, but not positioned or displayed. @@ -8487,7 +8580,7 @@ </section> <!-- End BeginEdit Event Handler --> <section id="evtTreeViewENDEDIT" xreflabel="ENDEDIT"><title>EndEdit Event Handler</title> -<indexterm><primary>TreeView Event</primary><secondary>ENDEDIT</secondary></indexterm> +<indexterm><primary>TreeView class</primary><secondary>events</secondary><tertiary>ENDEDIT</tertiary></indexterm> <para> The event handler for the ENDEDIT event is invoked when the user finishes a label editing operation on an item of the tree-view. A label editing operation is only available when the tree-view has the <xref linkend="styTreeViewEDIT"/> style. @@ -8683,7 +8776,7 @@ <section id="evtTreeViewEXPANDED" xreflabel="EXPANDED"><title>Expanded Event Handler</title> -<indexterm><primary>TreeView Event</primary><secondary>EXPANDED</secondary></indexterm> +<indexterm><primary>TreeView class</primary><secondary>events</secondary><tertiary>EXPANDED</tertiary></indexterm> <para> The event handler for the EXPANDED event is invoked when after a tree-view item has been expanded or collapsed. </para> @@ -8780,7 +8873,7 @@ <section id="evtTreeViewEXPANDING" xreflabel="EXPANDING"><title>Expanding Event Handler</title> -<indexterm><primary>TreeView Event</primary><secondary>EXPANDING</secondary></indexterm> +<indexterm><primary>TreeView class</primary><secondary>events</secondary><tertiary>EXPANDING</tertiary></indexterm> <para> The event-handling method connected to the EXPANDING event receives four arguments: the control ID of the tree view control, the handle of the tree item that is about to be expanded or collapsed, a string that indicates whether the item @@ -8907,7 +9000,7 @@ <section id="evtTreeViewGETINFOTIP"><title>GetInfoTip Event Handler</title> -<indexterm><primary>TreeView Event</primary><secondary>GETINFOTIP</secondary></indexterm> +<indexterm><primary>TreeView class</primary><secondary>events</secondary><tertiary>GETINFOTIP</tertiary></indexterm> <para> The event handler method connected to the get info tip event is invoked when the tree-view control requests the text to display in the info tip. The programmer must return a string value and the interpreter waits for this return. The <emphasis @@ -9004,7 +9097,7 @@ <section id="evtTreeViewKEYDOWN" xreflabel="KEYDOWN"><title>KeyDown Event Handler</title> -<indexterm><primary>TreeView Event</primary><secondary>KEYDOWN</secondary></indexterm> +<indexterm><primary>TreeView 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 within the tree-view control. The event handler is similar to the event handler for the <link linkend="evtTreeViewKEYDOWNEX">KEYDOWNEX</link> event, it is invoked @@ -9083,7 +9176,7 @@ <section id="evtTreeViewKEYDOWNEX" xreflabel="KEYDOWNEX"><title>KeyDown (extended) Event Handler</title> -<indexterm><primary>TreeView Event</primary><secondary>KEYDOWNEX</secondary></indexterm> +<indexterm><primary>TreeView class</primary><secondary>events</secondary><tertiary>KEYDOWNEX</tertiary></indexterm> <para> The event-handling method connected through the KEYDOWNEX keyword is similar to the event handler for the KEYDOWN event handler. It is invoked for the same event, when the user presses a key within the tree-view. However, it receives a Modified: docs/trunk/oodialog/en-US/overview.xml =================================================================== --- docs/trunk/oodialog/en-US/overview.xml 2012-11-22 19:16:14 UTC (rev 8615) +++ docs/trunk/oodialog/en-US/overview.xml 2012-11-22 21:57:28 UTC (rev 8616) @@ -765,35 +765,40 @@ class. The connected methods are often called <emphasis role="italic">event handlers</emphasis> because the code in the method handles the event. </para> -<para id="ovvEventsDirectReply" xreflabel="directly"> - Event notification messages in Windows fall into two groups, messages where the reply is ignored and messages where - the reply is significant. Prior to the introduction of the C++ <link linkend="sctHistory">native</link> APIs, there was - <emphasis role="bold">no way</emphasis> in ooDialog to <emphasis role="italic">directly</emphasis> reply to the - notification message. This placed a severe restriction on ooDialog programs. Many of the features of the operating - system could not be used with this restriction. For instance, when a user selects a new tab in a - <xref linkend="clsTab"/> control, the operating system sends a SELCHANGING event notification before the selected - tab is changed. The programmer can allow or prevent the change by replying true or false to the notification message. -</para> -<para> - Without the ability to reply directly to the notification, the ooDialog programmer could not take advantage of the - SELCHANGING notification. The introduction of the C++ native APIs in ooRexx 4.0.0 removed this restriction. Beginning - in ooDialog 4.2.0, the event handling methods in the Rexx dialog object can be directly invoked from the Windows - message processing loop. This allows the Rexx dialog object to reply directly to the notification message. -</para> -<para> - In addition, the underlying Windows message processing loop provides a form of synchronization in Windows - applications. Within the loop, a Windows application receives a message, processes it, then receives the next message, - processes it, and so on. In older ooDialog programs this syncronization was lost because ooDialog put the recieved - message on a queue, recieved the next message, put it on the queue, and continued. This meant that many messages could - be recieved in the processing loop before a single message was process by the ooDialog program. This loss of - synchronization caused ooDialog applications to perform poorly. -</para> -<para> - The ability to directly reply to event notifications greatly extends the power of the ooDialog framework. However, it - also changes how the ooDialog programmer must write his event handlers. In particular, the event handler must return - in a timely manner. This is discussed more <link linkend="sctCodingEventHandlers">fully</link>/> in the - <computeroutput>EventNotification</computeroutput> class documentation. -</para> +<variablelist> + <varlistentry id="ovvEventsDirectReply" xreflabel="directly"><term><emphasis role="bold">Directly Reply</emphasis></term> + <listitem> + <para> + Event notification messages in Windows fall into two groups, messages where the reply is ignored and messages where + the reply is significant. Prior to the introduction of the C++ <link linkend="sctHistory">native</link> APIs, there was + <emphasis role="bold">no way</emphasis> in ooDialog to <emphasis role="italic">directly</emphasis> reply to the + notification message. This placed a severe restriction on ooDialog programs. Many of the features of the operating + system could not be used with this restriction. For instance, when a user selects a new tab in a + <xref linkend="clsTab"/> control, the operating system sends a SELCHANGING event notification before the selected + tab is changed. The programmer can allow or prevent the change by replying true or false to the notification message. + </para> + <para> + Without the ability to reply directly to the notification, the ooDialog programmer could not take advantage of the + SELCHANGING notification. The introduction of the C++ native APIs in ooRexx 4.0.0 removed this restriction. Beginning + in ooDialog 4.2.0, the event handling methods in the Rexx dialog object can be directly invoked from the Windows + message processing loop. This allows the Rexx dialog object to reply directly to the notification message. + </para> + <para> + In addition, the underlying Windows message processing loop provides a form of synchronization in Windows + applications. Within the loop, a Windows application receives a message, processes it, then receives the next message, + processes it, and so on. In older ooDialog programs this syncronization was lost because ooDialog put the recieved + message on a queue, recieved the next message, put it on the queue, and continued. This meant that many messages could + be recieved in the processing loop before a single message was process by the ooDialog program. This loss of + synchronization caused ooDialog applications to perform poorly. + </para> + <para> + The ability to directly reply to event notifications greatly extends the power of the ooDialog framework. However, it + also changes how the ooDialog programmer must write his event handlers. In particular, the event handler must return + in a timely manner. This is discussed more <link linkend="sctCodingEventHandlers">fully</link> in the + <computeroutput>EventNotification</computeroutput> class documentation. + </para> + </listitem></varlistentry> +</variablelist> </section> <section id="ovvInaccurate" xreflabel="inaccurate"><title>factorX / factorY</title> Modified: docs/trunk/oodialog/en-US/tooltip.xml =================================================================== --- docs/trunk/oodialog/en-US/tooltip.xml 2012-11-22 19:16:14 UTC (rev 8615) +++ docs/trunk/oodialog/en-US/tooltip.xml 2012-11-22 21:57:28 UTC (rev 8616) @@ -82,20 +82,21 @@ or return information using a <computeroutput>ToolInfo</computeroutput> object. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Instantiation:</emphasis></term> + <varlistentry><term><emphasis role="bold">Creation:</emphasis></term> <listitem> <para> - Use the <link linkend="tmthNewToolTip">newToolTip</link> method of the <link linkend="chpDialogObject">dialog</link> - object to retrieve a new ToolTip object. + Unlike most other types of dialog controls, a ToolTip can not be added to a dialog <link + linkend="ovvDialogTemplate">template</link>. ToolTips are created dynamically using the <link + linkend="tmthCreateToolTip">createToolTip</link> method. ToolTips can only be created after the underlying Windows dialog + exists. Therefore, ToolTips can not be created in the <xref linkend="mthDefineDialog"/> method of the <link + linkend="clsUserDialog">UserDialog</link> class. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Dynamic Definition:</emphasis></term> + <varlistentry><term><emphasis role="bold">Instantiation:</emphasis></term> <listitem> <para> - Unlike most other types of dialog controls, a ToolTip can not be added to a dialog <link - linkend="ovvDialogTemplate">template</link>. ToolTips are created dynamically during the <link - linkend="tmthNewToolTip">newToolTip</link> method. Therefore there is no equivalent <emphasis - role="italic">createToolTip</emphasis> method in the <link linkend="clsUserDialog">UserDialog</link> class. + Use the <link linkend="tmthNewToolTip">newToolTip</link> method of the <link linkend="chpDialogObject">dialog</link> + object to retrieve the Rexx ToolTip object. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Event Notification</emphasis></term> @@ -109,7 +110,6 @@ <section id="sctToolIdentification"><title>Tool Identification</title> -<indexterm><primary>ToolTip tool identification</primary></indexterm> <indexterm><primary>ToolTip class</primary><secondary>tool identification</secondary></indexterm> <para> @@ -396,7 +396,7 @@ <section id="tmthCreateToolTip"><title>createToolTip (dialog object method)</title> <para> To create the underlying Windows ToolTip control use the <link linkend="mthCreateToolTip">createToolTip</link> method of - the <link linkend="chpDialogObject">dialog</link> object. This method always returns the instantiated Rexx object that + the <link linkend="chpDialogObject">dialog</link> object. This method also returns the instantiated Rexx object that represents the created tool tip control. The basic syntax is: <programlisting> @@ -411,10 +411,10 @@ <section id="tmthNewToolTip"><title>newToolTip (dialog object method)</title> <para> - ToolTip objects can not be instantiated by the programmer from Rexx code. Rather a ToolTip object is obtained either by - using the <xref linkend="mthCreateToolTip"/> method or the <link linkend="mthNewToolTip">newToolTip</link> method of - the dialog <link linkend="chpDialogObject">object</link>. The syntax for the <emphasis role="italic">newToolTip</emphasis> - is: + ToolTip objects can not be instantiated by the programmer from Rexx code using the normal <emphasis + role="italic">new</emphasis> method. Rather a ToolTip object is obtained either by using the <xref + linkend="mthCreateToolTip"/> method or the <link linkend="mthNewToolTip">newToolTip</link> method of the dialog <link + linkend="chpDialogObject">object</link>. The syntax for the <emphasis role="italic">newToolTip</emphasis> is: <programlisting> <![CDATA[ >>-newToolTip(--id--)--------------------->< @@ -2820,7 +2820,7 @@ </section> <!-- End ToolTip::updateTipText() --> -<section id="clsToolInfo" xreflabel="ToolInf"><title>ToolInfo Class</title> +<section id="clsToolInfo" xreflabel="ToolInfo"><title>ToolInfo Class</title> <indexterm><primary>ToolInfo class</primary></indexterm> <para> A <emphasis role="italic">ToolInfo</emphasis> object contains information about a tool in a <xref linkend="clsToolTip"/> Modified: docs/trunk/oodialog/en-US/treeview.xml =================================================================== --- docs/trunk/oodialog/en-US/treeview.xml 2012-11-22 19:16:14 UTC (rev 8615) +++ docs/trunk/oodialog/en-US/treeview.xml 2012-11-22 21:57:28 UTC (rev 8616) @@ -2670,7 +2670,7 @@ <section id="mthRoot"><title>root</title> <indexterm><primary>root</primary></indexterm> -<indexterm><primary>TreeView</primary><secondary>root</secondary></indexterm> +<indexterm><primary>TreeView class</primary><secondary>root</secondary></indexterm> <programlisting> <![CDATA[ >>--root----------------------------------------->< |
From: <mie...@us...> - 2012-11-23 04:01:40
|
Revision: 8620 http://sourceforge.net/p/oorexx/code-0/8620 Author: miesfeld Date: 2012-11-23 04:01:36 +0000 (Fri, 23 Nov 2012) Log Message: ----------- #419 Add Tooltip control See ticket [Feature-Requests:#419] Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml docs/trunk/oodialog/en-US/overview.xml docs/trunk/oodialog/en-US/tooltip.xml docs/trunk/oodialog/en-US/userdialog.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-23 03:49:09 UTC (rev 8619) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-23 04:01:36 UTC (rev 8620) @@ -653,6 +653,10 @@ <entry>Connects an event notification from a tab control to a method in the Rexx dialog.</entry> </row> <row> +<entry><xref linkend="mthConnectToolTipEvent"/></entry> +<entry>Connects an event notification from a ToolTip control to a method in the Rexx dialog.</entry> +</row> +<row> <entry><xref linkend="mthConnectTrackBarEvent"/></entry> <entry>Connects an event notification from a track bar control to a method in the Rexx dialog.</entry> </row> @@ -7576,7 +7580,7 @@ </para> <para> By default, the interpreter waits for the return from the event handler for this event and the event handler must return a - value. The actual value of the return has no meeting. This behaviour can be changed through the <emphasis + value. The actual value of the return has no meaning. This behaviour can be changed through the <emphasis role="italic">willReply</emphasis> argument to the <xref linkend="mthConnectToolTipEvent"/> method. If <emphasis role="italic">willReply</emphasis> is false, the interpreter does not wait for the return. </para> @@ -7712,8 +7716,9 @@ <varlistentry><term>ABSOLUTE</term> <listitem> <para> - The ToolTip window is positioned at the same coordinates provided by the <xref linkend="mthTrackPosition"/> - method. This flag must be used with the TRACK flag. + Positions the ToolTip window at the exact same coordinates specified by the <xref linkend="mthTrackPosition"/> + method. Without this flag the ToolTip control chooses where to display the ToolTip window based on the + coordinates specified, which places the ToolTip close to the tool. This flag must be used with the TRACK flag. </para> </listitem></varlistentry> <varlistentry><term>CENTERTIP</term> @@ -7784,7 +7789,7 @@ <listitem> <para> The following example shows a simple NEEDTEXT event handler that sets the tool tip text when the mouse hovers over a push - button. True is returned to indicate that the ToolTip should store the text for that tool and need not ask for it again? + button. True is returned to indicate that the ToolTip should store the text for that tool and need not ask for it again: <programlisting> <![CDATA[ @@ -7811,7 +7816,7 @@ </para> <para> By default, the interpreter waits for the return from the event handler for this event and the event handler must return a - value. The actual value of the return has no meeting. This behaviour can be changed through the <emphasis + value. The actual value of the return has no meaning. This behaviour can be changed through the <emphasis role="italic">willReply</emphasis> argument to the <xref linkend="mthConnectToolTipEvent"/> method. If <emphasis role="italic">willReply</emphasis> is false, the interpreter does not wait for the return. </para> @@ -7850,7 +7855,7 @@ <varlistentry><term><emphasis role="bold">Return:</emphasis></term> <listitem> <para> - The actual value of the return has no meaning. + The actual value of the return has no meaning. 0 makes a good return value. </para> </listitem></varlistentry> </variablelist> @@ -7871,7 +7876,7 @@ </programlisting> <para> - The event handler for the tool tip SHOW event is invoked when the ToolTip is about to display its window. + The event handler for the SHOW event is invoked when the ToolTip is about to display its window. </para> <para> The programmer must alwayse return a value from the event handler and the interpreter waits for this return. The <emphasis @@ -7919,7 +7924,7 @@ <para> A ToolTip's window rectangle is somewhat larger than its text display rectangle, and its origin is offset up and to the left. If the application needs to accurately position the text display rectangle of a ToolTip, use the <xref - linkend="mthAdjustRect"/> mehtod converts a text display rectangle into the corresponding ToolTip window rectangle and + linkend="mthAdjustRect"/> method converts a text display rectangle into the corresponding ToolTip window rectangle and vice versa. </para> </listitem></varlistentry> @@ -7934,14 +7939,14 @@ <![CDATA[ ::method onShow unguarded - expose clRect1 clRect2 clRect3 clRect4 + expose r1 r2 r3 r4 use arg toolID, toolTip select - when toolID == .constDir[IDTOOL_DLG_RECT1] then pos = .Point~new(clRect1~left, clRect1~top) - when toolID == .constDir[IDTOOL_DLG_RECT2] then pos = .Point~new(clRect2~left, clRect2~top) - when toolID == .constDir[IDTOOL_DLG_RECT3] then pos = .Point~new(clRect3~left, clRect3~top) - when toolID == .constDir[IDTOOL_DLG_RECT4] then pos = .Point~new(clRect4~left, clRect4~top) + when toolID == .constDir[IDTOOL_DLG_RECT1] then pos = .Point~new(r1~left, r1~top) + when toolID == .constDir[IDTOOL_DLG_RECT2] then pos = .Point~new(r2~left, r2~top) + when toolID == .constDir[IDTOOL_DLG_RECT3] then pos = .Point~new(r3~left, r3~top) + when toolID == .constDir[IDTOOL_DLG_RECT4] then pos = .Point~new(r4~left, r4~top) otherwise pos = .Point~new end -- End select Modified: docs/trunk/oodialog/en-US/overview.xml =================================================================== --- docs/trunk/oodialog/en-US/overview.xml 2012-11-23 03:49:09 UTC (rev 8619) +++ docs/trunk/oodialog/en-US/overview.xml 2012-11-23 04:01:36 UTC (rev 8620) @@ -804,8 +804,8 @@ <section id="ovvInaccurate" xreflabel="inaccurate"><title>factorX / factorY</title> <para> The <emphasis role="italic">factorX</emphasis> and <emphasis role="italic">factorY</emphasis> attributes of the - <xref linkend="chpDialogObject"/> object were intended to provide a way to convert between - <xref linkend="defPixel"/>s and <xref linkend="defDialogUnit"/>, and vice versa. Although their + <xref linkend="chpDialogObject"/> object were intended to provide a way to convert between <link + linkend="defPixel">pixels</link> and dialog <link linkend="defDialogUnit">units</link>, and vice versa. Although their values may have been correct when ooDialog was originally <link linkend="sctHistory">designed</link>, in almost all cases the values are now incorrect. The method used to calculate the ratio between dialog units and pixels is not correct. </para> Modified: docs/trunk/oodialog/en-US/tooltip.xml =================================================================== --- docs/trunk/oodialog/en-US/tooltip.xml 2012-11-23 03:49:09 UTC (rev 8619) +++ docs/trunk/oodialog/en-US/tooltip.xml 2012-11-23 04:01:36 UTC (rev 8620) @@ -59,9 +59,9 @@ <para> ToolTip controls can display single or multiple lines of text. They can have square or rounded corners. They might or might not have a stem that points to the tools like a cartoon balloon. ToolTip text can be stationary or can move with the mouse - pointer, called tracking ToolTips. Stationary text can be displayed adjacent to a tool or it can be displayed over a tool, - which is referred to as in-place ToolTips. Standard ToolTips are stationary, display a single line of text, have square - corners, and have no stem pointing to the tool. + pointer, these are called tracking ToolTips. Stationary text can be displayed adjacent to a tool or it can be displayed + over a tool, which is referred to as in-place ToolTips. Standard ToolTips are stationary, display a single line of text, + have square corners, and have no stem pointing to the tool. </para> <para> The <computeroutput>ToolTip</computeroutput> class provides methods to work with and manipulate the underlying Windows @@ -96,7 +96,7 @@ <listitem> <para> Use the <link linkend="tmthNewToolTip">newToolTip</link> method of the <link linkend="chpDialogObject">dialog</link> - object to retrieve the Rexx ToolTip object. + object to retrieve a Rexx ToolTip object. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Event Notification</emphasis></term> @@ -214,7 +214,7 @@ </row> <row> <entry><link linkend="tmthCreateToolTip">createToolTip</link></entry> -<entry>Creates the underlying Windows ToolTip control and returns an instantiated Rexx <xref linkend="clsToolTip"/> object.</entry> +<entry>Creates the underlying Windows ToolTip control and returns an instantiated Rexx ToolTip object.</entry> </row> <row> <entry><link linkend="tmthConnectToolTipEvent">connectToolTipEvent</link></entry> @@ -230,19 +230,19 @@ </row> <row> <entry><xref linkend="mthActivate"/></entry> -<entry>x</entry> +<entry>Activates or deactivates this ToolTip.</entry> </row> <row> <entry><xref linkend="mthAddTool"/></entry> -<entry>x</entry> +<entry>Adds a tool to this ToolTip.</entry> </row> <row> <entry><xref linkend="mthAddToolEx"/></entry> -<entry>x</entry> +<entry>Adds the tool, specified by a <computeroutput>ToolInfo</computeroutput> object, to this ToolTip.</entry> </row> <row> <entry><xref linkend="mthAddToolRect"/></entry> -<entry>x</entry> +<entry>Adds a tool that uses a rectangular area in the dialog as its trigger point.</entry> </row> <row> <entry><xref linkend="mthAdjustRect"/></entry> @@ -384,9 +384,8 @@ linkend="chpDialogObject">dialog</link> object. The basic syntax is: <programlisting> <![CDATA[ ->>-connectToolTipEvent(--id--,--event--+----------------+--)------------>< - +--,-methodName--+ - +>>--connectToolTipEvent(--id--,--event--+-----------+--+-------------+--)------>< + +-,-mthName-+ +-,-willReply-+ ]]> </programlisting> </para> @@ -425,7 +424,7 @@ </section> <!-- End newToolTip() [PlainBaseDialog method] --> -<section id="mthActivate"><title>activate</title> +<section id="mthActivate" xreflabel="activate"><title>activate</title> <indexterm><primary>activate</primary></indexterm> <indexterm><primary>ToolTip class</primary><secondary>activate</secondary></indexterm> <programlisting> @@ -437,7 +436,7 @@ </programlisting> <para> - Activates or deactivates this tool tip. + Activates or deactivates this ToolTip. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -446,10 +445,10 @@ The single optional argument is: </para> <variablelist> - <varlistentry><term>activate</term> + <varlistentry><term>activate [optional]</term> <listitem> <para> - If true activates this tool it, if false deactivate this tool tip. The default if the argument is omitted is true. + If true, activates this tool it, if false, deactivate this tool tip. The default if the argument is omitted is true. </para> </listitem></varlistentry> </variablelist> @@ -488,7 +487,7 @@ </programlisting> <para> - Adds a tool to this tool tip. + Adds a tool to this ToolTip. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -506,18 +505,18 @@ <varlistentry><term>text [optional]</term> <listitem> <para> - Text for the tool. If omitted, or the empty string, or the string: TEXTCALLBACK then the tool tip sends the NEEDTEXT - notification and the program supplies the text. + Text for the tool. If omitted, or the empty string, or the string: TEXTCALLBACK, then the tool tip sends the <xref + linkend="kywToolTipNEEDTEXT"/> notification and the program supplies the text. </para> <para> - The maximum length of the text is 1023 characters, which includes any possible end of line (0x0D0A) sequences. + The length of the text must be less than 1024 characters, which includes any possible end of line (0x0D0A) sequences. </para> </listitem></varlistentry> <varlistentry><term>flags [optional]</term> <listitem> <para> A list of 0 or more of the following keywords separated by spaces, case is not significant. If this argument is - omitted, the flags are set to ISISHWND SUBCLASS: + omitted, the flags are set to IDISHWND SUBCLASS: </para> <para> <simplelist type='vert' columns='3'> @@ -534,9 +533,9 @@ <varlistentry><term>ABSOLUTE</term> <listitem> <para> - Positions the ToolTip window at the same coordinates provided by the <xref linkend="mthTrackPosition"/> method. - This flag must be used with the TRACK flag. This flag is not useful for the simple case the <emphasis - role="italic">addTool</emphasis> method is designed for. + Positions the ToolTip window at the exact same coordinates specified by the <xref linkend="mthTrackPosition"/> + method. Without this flag the ToolTip control chooses where to display the ToolTip window based on the + coordinates specified, which places the ToolTip close to the tool. This flag must be used with the TRACK flag. </para> </listitem></varlistentry> <varlistentry><term>CENTERTIP</term> @@ -553,7 +552,8 @@ role="italic">addTool</emphasis> method, the ooDialog framework always sets this flag, it does not need to be specified by the programmer. The window <link linkend="defHandle">handle</link> of the <emphasis role="italic">tool</emphasis> argument is always the ID part of the tool identification. - </para> </listitem></varlistentry> + </para> + </listitem></varlistentry> <varlistentry id="kywToolTipPARSELINKS" xreflabel="PARSELINKS"><term>PARSELINKS</term> <listitem> <para> @@ -585,8 +585,7 @@ <para> Positions the ToolTip window next to the tool to which it corresponds and moves the window according to coordinates supplied by the <xref linkend="mthTrackPosition"/> method. The programmer must activate this - type of tool using the <xref linkend="mthTrackActivate"/> method. This flag is not useful for the simple case - the <emphasis role="italic">addTool</emphasis> method is designed for. + type of tool using the <xref linkend="mthTrackActivate"/> method. </para> </listitem></varlistentry> <varlistentry><term>TRANSPARENT</term> @@ -611,13 +610,15 @@ <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns true on success, false on error. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + The <emphasis role="italic">addTool</emphasis> method is intended to be a convenient method for use in the most common + case of adding a tool. The case where the tool is a simple dialog control. Use the <xref linkend="mthAddToolRect"/> or + the <xref linkend="mthAddToolEx"/> methods to add a tool with characteristics that need to be more explicitly defined. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> @@ -625,17 +626,22 @@ <para> Raises syntax errors when incorrect usage is detected. </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example creates a ToolTip and then adds a tool to it. The tool is defined using a push button dialog control and + the text for the tool is specified at the time the tool is added: <programlisting> <![CDATA[ + pbTest = self~newPushButton(IDC_PB_TEST) + count = 0 + ... + + ttTest = self~createToolTip(IDC_TT_TEST) + ttTest~addTool(pbTest, "Push the Test button to start the regression testing.") + ]]> </programlisting> </para> @@ -649,25 +655,24 @@ <indexterm><primary>ToolTip class</primary><secondary>addToolEx</secondary></indexterm> <programlisting> <![CDATA[ ->>--addToolEx(--+--------+--)--------------------------------------------->< - +--type--+ +>>--addToolEx(--tool--)-------------------------->< ]]> </programlisting> <para> - xx + Adds the specified tool to this ToolTip. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The arguments are: + The single argument is: </para> <variablelist> - <varlistentry><term>TERM</term> + <varlistentry><term>tool [required]</term> <listitem> <para> - xx + A <xref linkend="clsToolInfo"/> object that defines the tool being added. </para> </listitem></varlistentry> </variablelist> @@ -675,31 +680,44 @@ <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns true on success, false on error. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + There are a number of different attributes that can be set when adding a tool to a tool tip. The <emphasis + role="italic">addToolEx</emphasis> method is designed to let the programmer specify any valid combination of attributes + allowed by the operating system. To do this, it requires the specifier of the tool to be a + <computeroutput>ToolInfo</computeroutput> object. The programmer is responsible for setting the tool attriubtes as he + wishes. </para> + <para> + For the simple case of adding a tool that is a dialog control, the <xref linkend="mthAddTool"/> is a more convenient + method. + </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> <listitem> <para> Raises syntax errors when incorrect usage is detected. </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example creates a ToolTip and then adds a tool that will supply customized tool tips for a tree-view: <programlisting> <![CDATA[ + tv = self~newTreeView(IDC_TREE) + rect = tv~clientRect + + tt = self~createToolTip(IDC_TT) + + toolInfo = .ToolInfo~new(tv, ID_TREE_TOOL, '', 'TRANSPARENT', rect) + tt~addToolEx(toolInfo) + ]]> </programlisting> </para> @@ -713,13 +731,13 @@ <indexterm><primary>ToolTip class</primary><secondary>addToolRect</secondary></indexterm> <programlisting> <![CDATA[ ->>--addToolRect(--+--------+--)--------------------------------------------->< - +--type--+ +>>--addToolRect(--dlg-,-id-,-rect--+--------+-+---------+-+------------+--)---->< + +-,-txt--+ +-,-flags-+ +-,-userData-+ ]]> </programlisting> <para> - xx + Adds a tool that uses a rectangular area in the dialog as its trigger point. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -728,42 +746,171 @@ The arguments are: </para> <variablelist> - <varlistentry><term>TERM</term> + <varlistentry><term>dlg [required]</term> <listitem> <para> xx </para> </listitem></varlistentry> + <varlistentry><term>id [required]</term> + <listitem> + <para> + An unique, non-negative, whole number that identifies the tool being added. May be numeric or <xref + linkend="defSymbolic"/>. + </para> + </listitem></varlistentry> + <varlistentry><term>rect [required]</term> + <listitem> + <para> + A <xref linkend="clsRect"/> object that specifies the bounding rectangle coordinates of the tool. The coordinates are + in client <link linkend="defScreenCoordinates"></link> of the dialog identified by the <emphasis + role="italic">dlg</emphasis> argument. + </para> + </listitem></varlistentry> + <varlistentry><term>txt [optional]</term> + <listitem> + <para> + Text for the tool. If omitted, or the empty string, or the string: TEXTCALLBACK, then the ToolTip sends the <xref + linkend="kywToolTipNEEDTEXT"/> notification and the program supplies the text. + </para> + <para> + The length of the text must be less than 1024 characters, which includes any possible end of line (0x0D0A) sequences. + </para> + </listitem></varlistentry> + <varlistentry><term>flags [optional]</term> + <listitem> + <para> + A list of 0 or more of the following keywords separated by spaces, case is not significant. If this argument is + omitted, the flags are set to SUBCLASS: + </para> + <para> + <simplelist type='vert' columns='3'> + <member>ABSOLUTE </member> + <member>CENTERTIP </member> + <member>IDISHWND </member> + <member>PARSELINKS </member> + <member>RTLREADING </member> + <member>SUBCLASS </member> + <member>TRACK </member> + <member>TRANSPARENT</member> + </simplelist> + <variablelist> + <varlistentry><term>ABSOLUTE</term> + <listitem> + <para> + Positions the ToolTip window at the exact same coordinates specified by the <xref linkend="mthTrackPosition"/> + method. Without this flag the ToolTip control chooses where to display the ToolTip window based on the + coordinates specified, which places the ToolTip close to the tool. This flag must be used with the TRACK flag. + </para> + </listitem></varlistentry> + <varlistentry><term>CENTERTIP</term> + <listitem> + <para> + Centers the ToolTip window below the tool specified by the <emphasis role="italic">tool</emphasis> argument. + </para> + </listitem></varlistentry> + <varlistentry><term>IDISHWND</term> + <listitem> + <para> + Indicates that the ID part of the tool <link linkend="sctToolIdentification">identification</link> is the window + handle to the tool. This flag can not be used for the <emphasis role="italic">addToolRect</emphasis> method. If + it is present, the ooDialog framework removes it. + </para> + </listitem></varlistentry> + <varlistentry id="kywToolTipPARSELINKS" xreflabel="PARSELINKS"><term>PARSELINKS</term> + <listitem> + <para> + Requires Common Control <xref linkend="ovvComctl32"/> version 6.0 or later. + </para> + <para> + Indicates that links in the ToolTip text should be parsed. + </para> + </listitem></varlistentry> + <varlistentry><term>RTLREADING</term> + <listitem> + <para> + Indicates that the ToolTip text will be displayed in the opposite direction to the text in the parent window. + </para> + </listitem></varlistentry> + <varlistentry><term>SUBCLASS</term> + <listitem> + <para> + Indicates that the ToolTip control should subclass the tool's window to intercept messages, such as WM_MOUSEMOVE. + If this flag is not set, some means must be used so that the mouse messages are forwarded to the ToolTip control. + For the use case that the <emphasis role="italic">addToolRect</emphasis> method is designed for, this flag + should always be set. The ooDialog framwork always sets this flag during the <emphasis + role="italic">addToolRect</emphasis> method, the programmer does not need to include this flag. + </para> + </listitem></varlistentry> + <varlistentry><term>TRACK</term> + <listitem> + <para> + Positions the ToolTip window next to the tool to which it corresponds and moves the window according to + coordinates supplied by the <xref linkend="mthTrackPosition"/> method. The programmer must activate this + type of tool using the <xref linkend="mthTrackActivate"/> method. + </para> + </listitem></varlistentry> + <varlistentry><term>TRANSPARENT</term> + <listitem> + <para> + Causes the ToolTip control to forward mouse event messages to the parent window. This is limited to mouse events + that occur within the bounds of the ToolTip window. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term>userData [optional]</term> + <listitem> + <para> + A user data value to be associated with the tool. This can be any Rexx object the programmer wants. Note that the + value is associated with the tool, not the tool tip. + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns true on success, false on error. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> - <listitem> - <para> - Additional comments. - </para> - </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> <listitem> <para> Raises syntax errors when incorrect usage is detected. </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example was created solely as a demonstration of how ToolTips work, it has no real practical value. It displays + ToolTips as the mouse moves over a dialog: <programlisting> <![CDATA[ + tt = self~createToolTip(IDC_TT_MAIN) + + clRect = self~clientRect + hMidpoint = trunc((clRect~right - clRect~left) / 2) + clRect~left + vMidpoint = trunc((clRect~bottom - clRect~top) / 2) + clRect~top + + clRect1 = .Rect~new(clRect~left, clRect~top, hMidpoint, vMidpoint) + clRect2 = .Rect~new(hMidpoint + 1, clRect~top, clRect~right, vMidpoint + 1) + clRect3 = .Rect~new(clRect~left, vMidpoint + 1, hMidpoint + 1, clRect~bottom) + clRect4 = .Rect~new(hMidpoint + 1, vMidpoint + 1, clRect~right, clRect~bottom) + + text1 = 'Over main dialog, top left quadrant' + text2 = 'Over main dialog, top right quadrant' + text3 = 'Over main dialog, bottom left quadrant' + text4 = 'Over main dialog, bottom right quadrant' + + ret = tt~addToolRect(self, IDTOOL_DLG_RECT1, clRect1, text1, 'TRANSPARENT') + ret = tt~addToolRect(self, IDTOOL_DLG_RECT2, clRect2, text2, 'TRANSPARENT') + ret = tt~addToolRect(self, IDTOOL_DLG_RECT3, clRect3, text3, 'TRANSPARENT') + ret = tt~addToolRect(self, IDTOOL_DLG_RECT4, clRect4, text4, 'TRANSPARENT') + + self~connectToolTipEvent(IDC_TT_MAIN, 'SHOW', onShow) ]]> </programlisting> </para> Modified: docs/trunk/oodialog/en-US/userdialog.xml =================================================================== --- docs/trunk/oodialog/en-US/userdialog.xml 2012-11-23 03:49:09 UTC (rev 8619) +++ docs/trunk/oodialog/en-US/userdialog.xml 2012-11-23 04:01:36 UTC (rev 8620) @@ -11170,8 +11170,8 @@ <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example demonstrates how to create a push <xref linkend="mthCreatePushButton"/> and an - <xref linkend="mthCreateEdit"/> control in a dialog: + This example demonstrates how to create a push <link linkend="mthCreatePushButton">button</link> and an <link + linkend="mthCreateEdit"></link> control in a dialog: <programlisting> <![CDATA[ |
From: <mie...@us...> - 2012-11-28 00:48:46
|
Revision: 8631 http://sourceforge.net/p/oorexx/code-0/8631 Author: miesfeld Date: 2012-11-28 00:48:43 +0000 (Wed, 28 Nov 2012) Log Message: ----------- #499 ooDialog connectTreeViewEvent CHANGING veto See ticket [Feature-Requests:#499] Modified Paths: -------------- docs/trunk/oodialog/en-US/dialogObject.xml docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/dialogObject.xml =================================================================== --- docs/trunk/oodialog/en-US/dialogObject.xml 2012-11-27 04:24:02 UTC (rev 8630) +++ docs/trunk/oodialog/en-US/dialogObject.xml 2012-11-28 00:48:43 UTC (rev 8631) @@ -4750,8 +4750,8 @@ EventNotification::<xref linkend="mthConnectTreeViewEvent"/> <![CDATA[ ->>--connectTreeViewEvent(--id--,--event--+---------------+--)------------------>< - +-,--methodName-+ +>>-connectTreeViewEvent(--id--,--event--+-------------+--+-------------+--)---->< + +-,--mthName--+ +-,-willReply-+ ]]> </programlisting> </section> Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-27 04:24:02 UTC (rev 8630) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-28 00:48:43 UTC (rev 8631) @@ -8271,13 +8271,6 @@ role="italic">willReply</emphasis> is <computeroutput>.true</computeroutput>, the interpreter waits until the event handling method returns a value. </para> - <para> - <emphasis role="bold">Note:</emphasis> Currently the <emphasis role="italic">willReply</emphasis> argument is ignored - for all events except the BEGINEDIT, ENDEDIT, EXPANDING, EXPANDED, and KEYDOWNEX events. For the GETINFOTIP event, the - interpreter always waits for the reply. For all other events, the interpreter never waits for the reply from the event - handler. Future enhancements to the <computeroutput>TreeView</computeroutput> class may allow the <emphasis - role="italic">willReply</emphasis> to have effect for all tree-view event notifications. - </para> </listitem></varlistentry> </variablelist> </listitem></varlistentry> @@ -8313,6 +8306,25 @@ 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> + <emphasis role="bold">Note:</emphasis> The original implementation of ooDialog was limited in the arguments sent to the + event handlers for many event notifications. In many cases, the Windows notification provides more information than was + provided to the event handlers in the original implementation. Many of the event notifications for the tree-view have + been enhanced to provide the event handlers with more complete information. To maintain backwards compatibility, if the + <emphasis role="italic">willReply</emphasis> argument is omitted, the old event notification implementation is used. To + use the enhanced implementation, the programmer simply includes the <emphasis role="italic">willReply</emphasis> + argument. Whether the argument is false or true does not matter. It is the process of including the argument that signals + the programmer wants to use the enhanced notification. + </para> + <para> + However, the <emphasis role="italic">willReply</emphasis> argument is ignored for the GETINFOTIP event. For this + event, the interpreter always waits for the reply. If the programmer does not wish to return a value from the event + handler for the GETINFOTIP, then he should not connect that event. + </para> + <para> + For each tree-view event keyword, there is a section describing the details of the event handler for that keyword. These + sections immediately follow this section. + </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details:</emphasis></term> <listitem> @@ -8337,11 +8349,11 @@ ::class 'FileDlg' subclass UserDialog ::method init - self~connectTreeViewEvent(IDC_TV_FILES, "SELCHANGED", "newTreeSelection") + self~connectTreeViewEvent(IDC_TV_FILES, "SELCHANGED", "newTreeSelection", .true) ::method newTreeSelection unguarded - tc = self~newTreeView(IDC_TV_FILES) - text = tc~itemText(tc~selected) + use arg id, hItemOld, userOld, hItemNew, userNew, action, rxTv + textNew = rxTv~itemText(hItemNew) say "The label of the new selection is:" text return 0 @@ -8351,37 +8363,151 @@ </listitem></varlistentry> </variablelist> -<section id="evtTreeViewBEGINDRAG" xreflabel="BEGINDRAG"><title>BeginDrag Event Handler</title> +<section id="evtTreeViewBEGINDRAG" xreflabel="BEGINDRAG"><title>BeginDrag / BeginRDrag Event Handler</title> <indexterm><primary>TreeView class</primary><secondary>events</secondary><tertiary>BEGINDRAG</tertiary></indexterm> +<indexterm><primary>TreeView class</primary><secondary>events</secondary><tertiary>BEGINRDRAG</tertiary></indexterm> <para> - The event-handling method connected to BEGINDRAG receives three arguments: the control ID of the tree view control, the - tree item to be dragged, and the point where the mouse cursor was pressed (x and y positions, separated by a blank). - Example: + The event handler for the BEGINDRAG event is invoked when a drag-and-drop operation involving the left mouse button is + being initiated in the tree-view. The event handler for the BEGINRDRAG event is invoked when a drag-and-drop operation + involving the right mouse button is being initiated in the tree-view. The arguments sent to, and the behaviour of, both + event handlers is identical. Both event handlers are described in this single section. +</para> +<para> + 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="mthConnectTreeViewEvent"/> method is omitted the old + implementation is used. If the argument is not omitted, the new implementation is used. In addition, ooDialog provides a + default handler for these events. If the <emphasis role="italic">mthName</emphasis> argument is specified as <emphasis + role="italic">defTreeDragHandler</emphasis>, then this default event handler is uesed. How the event handlers work is + described separately below: +</para> -<programlisting> -<![CDATA[ +<variablelist> + <varlistentry><term><emphasis role="bold">New event handler description:</emphasis></term> + <listitem> + <para> + Whether the programmer must return a value and if the interpreter waits, or does not wait, for this return is + determined by the value of the <emphasis role="italic">willReply</emphasis> argument. If <emphasis + role="italic">willReply</emphasis> is true, the programmer must return a value from the event handler and the + interpreter waits for that reply. If <emphasis role="italic">willReply</emphasis> is false the interpreter does not + wait for a reply. + </para> -::method onBeginDrag unguarded - use arg id, item, where - say "Item with handle" item "is in drag-and-drop mode" - parse var where x y - say "The drag operation started at point ("x","y")" + <programlisting> + <![CDATA[ + ::method onBeginDrag unguarded + use arg id, hItem, pos, treeView, userData - return 0 -]]> -</programlisting> + return 0 + ]]> + </programlisting> -</para> -</section> + <variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method receives 5 arguments: + </para> + <variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The resource id of the tree-view sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>hItem</term> + <listitem> + <para> + The tree-view item handle that is being dragged + </para> + </listitem></varlistentry> + <varlistentry><term>pos</term> + <listitem> + <para> + The position, in client <link linkend="defScreenCoordinates">co-ordinates</link>, where the drag started. <emphasis + role="italic">pos</emphasis> is a <xref linkend="clsPoint"/> object. + </para> + </listitem></varlistentry> + <varlistentry><term>treeView</term> + <listitem> + <para> + The Rexx tree-view object whose underlying tree-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="mthNewTreeView"/> method. + </para> + </listitem></varlistentry> + <varlistentry><term>userData</term> + <listitem> + <para> + The user <link linkend="mthSetItemDataClsTreeView">data</link> object assigned to the tree-view item being dragged. + If no user data has been assigned, this argument will be the <computeroutput>.nil</computeroutput> object. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + When the programmer used true for the <emphasis role="italic">willReply</emphasis> argument, the event handler must + return a value. However, the tree-view ignores the returned value, so any value can be used. 0 makes a good return. + If <emphasis role="italic">willReply</emphasis> is false, the event handler does not need to return a value. Good + practice would probably be to always return a value from an event handler. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Old event handler description:</emphasis></term> + <listitem> + <para> + The old style event notification is used when the programmer omits the <emphasis role="italic">willReply</emphasis> + argument in the invocation of the <xref linkend="mthConnectListViewEvent"/> method. The return from the event handler is + completely ignored, the interpreter does not wait for this return. + </para> -<section id="evtTreeViewBEGINRDRAG" xreflabel="BEGINRDRAG"><title>BeginRDrag Event Handler</title> -<indexterm><primary>TreeView class</primary><secondary>events</secondary><tertiary>BEGINRDRAG</tertiary></indexterm> + <programlisting> + <![CDATA[ + ::method onBeginDrag unguarded + use arg id, hItem, where + ]]> + </programlisting> -<para> - The event-handling method connected to BEGINRDRAG receives three arguments: the control ID of the tree view control, the - tree item to be dragged, and the point where the mouse cursor was pressed (x and y positions, separated by a blank). - Example: + <variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method receives 3 arguments: + </para> + <variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The resource id of the tree-view sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>hItem</term> + <listitem> + <para> + The handle to the tree-view item being dragged + </para> + </listitem></varlistentry> + <varlistentry><term>where</term> + <listitem> + <para> + Specifies the postion of the cursor when the drag operation was initiated as a 2 word string. The first word is the x + position, the second word is the y postion. The position is expressed in client <link + linkend="defScreenCoordinates">co-ordintates</link>. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + The return is ignored by the interpretr, the interpreter does not wait for the return. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> <programlisting> <![CDATA[ @@ -8396,10 +8522,25 @@ ]]> </programlisting> -</para> -</section> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">defTreeDragHandler event handler description:</emphasis></term> + <listitem> + <para> + If the <emphasis role="italic">mthName</emphasis> argument for the BEGINDRAG or BEGINRDRAG event connections is <emphasis + role="italic">defTreeDragHandler</emphasis>, then a method supplied by the ooDialog framework is connected. The + programmer does not take any other action. The programmer can use, or omit, the <emphasis + role="italic">willReply</emphasis> argument. If used the value can be either true or false. Since the ooDialog framework + is handling things internally the outcome is the same. + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End BeginDrag Event Handler --> + + <section id="evtTreeViewBEGINEDIT" xreflabel="BEGINEDIT"><title>BeginEdit Event Handler</title> <indexterm><primary>TreeView class</primary><secondary>events</secondary><tertiary>BEGINEDIT</tertiary></indexterm> <para> @@ -8440,13 +8581,13 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The event handling method receives 4 arguments: + The event handling method receives 5 arguments: </para> <variablelist> <varlistentry><term>id</term> <listitem> <para> - The resource id of the list-view sending the notification. + The resource id of the tree-view sending the notification. </para> </listitem></varlistentry> <varlistentry><term>hItem</term> @@ -8533,7 +8674,7 @@ <listitem> <para> The old style event notification is used when the programmer omits the <emphasis role="italic">willReply</emphasis> - argument in the invocation of the <xref linkend="mthConnectListViewEvent"/> method. The return from the event handler is + argument in the invocation of the <xref linkend="mthConnectTreeViewEvent"/> method. The return from the event handler is completely ignored, the interpreter does not wait for this return. </para> @@ -8554,7 +8695,7 @@ <varlistentry><term>id</term> <listitem> <para> - The resource id of the list-view sending the notification. + The resource id of the tree-view sending the notification. </para> </listitem></varlistentry> <varlistentry><term>hItem</term> @@ -8584,6 +8725,153 @@ </section> <!-- End BeginEdit Event Handler --> + +<section id="evtTreeViewDEFAULTEDIT" xreflabel="DEFAULTEDIT"><title>DefaultEdit Event Handler</title> +<indexterm><primary>TreeView class</primary><secondary>events</secondary><tertiary>DEFAULTEDIT</tertiary></indexterm> +<para> + When the programmer specifies the DEFAULTEDIT event keyword for the <emphasis role="italic">event</emphasis> argument in + the <xref linkend="mthConnectTreeViewEvent"/> method, the ooDialog framework handles both the BEGINEDIT and ENDEDIT events + internally. These events are only generated when the tree-view has the <xref linkend="styTreeViewEDIT"/> style. +</para> +<para> + The intenal handling of the events changes the label of the item if the user does not cancel the editing operation. If the + user cancels the editing operation, the original lable is left unchanged. Allowing ooDialog to handle these events is less + work for the programmer, but it is also inflexible. +</para> + +</section> <!-- End DefaultEdit Event Handler --> + + +<section id="evtTreeViewDELETE" xreflabel="DELETE"><title>Delete Event Handler</title> +<indexterm><primary>TreeView class</primary><secondary>events</secondary><tertiary>DELETE</tertiary></indexterm> +<para> + The event handler for the DELETE event is invoked when the user deletes an item in the tree-view. +</para> +<para> + This event notification has been enhanced since the original ooDialog implementation. If the <emphasis + role="italic">willReply</emphasis> argument to the <xref linkend="mthConnectTreeViewEvent"/> 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> + +<variablelist> + <varlistentry><term><emphasis role="bold">New event handler description:</emphasis></term> + <listitem> + <para> + Whether the programmer must return a value and if the interpreter waits, or does not wait, for this return is + determined by the value of the <emphasis role="italic">willReply</emphasis> argument. If <emphasis + role="italic">willReply</emphasis> is true, the programmer must return a value from the event handler and the + interpreter waits for that reply. If <emphasis role="italic">willReply</emphasis> is false the interpreter does not + wait for a reply. + </para> + + <programlisting> + <![CDATA[ + ::method onDelete unguarded + use arg, id, hItem, rxTv, userData + + return 0 + ]]> + </programlisting> + + <variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method receives 4 arguments: + </para> + <variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The resource id of the tree-view sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>hItem</term> + <listitem> + <para> + The tree-view item handle whose item is being deleted. + </para> + </listitem></varlistentry> + <varlistentry><term>rxTv</term> + <listitem> + <para> + The Rexx tree-view object whose underlying tree-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="mthNewTreeView"/> method. + </para> + </listitem></varlistentry> + <varlistentry><term>userData</term> + <listitem> + <para> + The user <link linkend="mthSetItemDataClsTreeView">data</link> object assigned to the tree-view item that is being + deleted. If no user data has been assigned, this argument will be the <computeroutput>.nil</computeroutput> object. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + When the programmer used true for the <emphasis role="italic">willReply</emphasis> argument, the event handler must + return a value. However, the tree-view ignores the returned value, so any value can be used. 0 makes a good return. + If <emphasis role="italic">willReply</emphasis> is false, the event handler does not need to return a value. Good + practice would probably be to always return a value from an event handler. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Old event handler description:</emphasis></term> + <listitem> + <para> + The old style event notification is used when the programmer omits the <emphasis role="italic">willReply</emphasis> + argument in the invocation of the <xref linkend="mthConnectTreeViewEvent"/> method. The return from the event handler is + completely ignored, the interpreter does not wait for this return. + </para> + + <programlisting> + <![CDATA[ + ::method onDelete unguarded + use arg id, useLess + ]]> + </programlisting> + + <variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method receives 2 arguments: + </para> + <variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The resource id of the tree-view sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>useLess</term> + <listitem> + <para> + This argument is a number that has no meaning within the Rexx code. It is the value the old implementation of the + event notification sent to the event handler. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + The interpreter does not wait for the return from the event handler, so the return has no meaning. Good practice would + be to return a value anyway. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> +</variablelist> + +</section> <!-- End Delete Event Handler --> + + <section id="evtTreeViewENDEDIT" xreflabel="ENDEDIT"><title>EndEdit Event Handler</title> <indexterm><primary>TreeView class</primary><secondary>events</secondary><tertiary>ENDEDIT</tertiary></indexterm> <para> @@ -8628,7 +8916,7 @@ <varlistentry><term>id</term> <listitem> <para> - The resource id of the list-view sending the notification. + The resource id of the tree-view sending the notification. </para> </listitem></varlistentry> <varlistentry><term>itemID</term> @@ -8647,7 +8935,7 @@ <varlistentry><term>listViewCtrl</term> <listitem> <para> - The Rexx list-view object whose underlying list-view control has sent the notification. This is a convenience for + The Rexx tree-view object whose underlying tree-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="mthNewListView"/> method. </para> @@ -8786,6 +9074,11 @@ The event handler for the EXPANDED event is invoked when after a tree-view item has been expanded or collapsed. </para> <para> + 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. +</para> +<para> If the <emphasis role="italic">willReply</emphasis> argument to <xref linkend="mthConnectTreeViewEvent"/> method is true, the interpreter will wait for the reply from the event handler. However Windows ignores the reply, so returning any value is sufficient. If <emphasis role="italic">willReply</emphasis> is false or omitted, the interpreter does not wait @@ -8880,41 +9173,24 @@ <section id="evtTreeViewEXPANDING" xreflabel="EXPANDING"><title>Expanding Event Handler</title> <indexterm><primary>TreeView class</primary><secondary>events</secondary><tertiary>EXPANDING</tertiary></indexterm> <para> - The event-handling method connected to the EXPANDING event receives four arguments: the control ID of the tree view - control, the handle of the tree item that is about to be expanded or collapsed, a string that indicates whether the item - will be expanded or collapsed, and a string with possible extra information.. Recall that the EXPANDING notification is - sent <emphasis role="italic">before</emphasis> the item is expanded or collapsed. + The event handler for the EXPANDING event is invoked <emphasis role="italic">before</emphasis> a tree-view item is + going to be expanded or collapsed. </para> <para> - The <emphasis role="italic">what</emphasis> argument will be either <emphasis role="italic">EXPANDED</emphasis> or - <emphasis role="italic">COLLAPSED</emphasis>. The <emphasis role="italic">extra</emphasis> arugment will usually be the - empty string. The Microsoft documentation seems to indicate that when an item is about to be expanded, the action may be - expanded partial and when the action is about to be collapsed, it may be collapsed and reset. If expanded partial is - detected, the <emphasis role="italic">extra</emphasis> argument will be <emphasis role="italic">PARTIAL</emphasis>. If - collapse and reset is detected, the <emphasis role="italic">extra</emphasis> argument will be <emphasis - role="italic">RESET</emphasis>. However, in testing, neither of these 2 actions were every detected and the Microsoft - documentation is unclear here. It may be that the <emphasis role="italic">extra</emphasis> argument will always be the - empty string. + 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. </para> <para> - Example: - -<programlisting> -<![CDATA[ -]]> -</programlisting> - -</para> -<para> - The event handler for the EXPANDING event is invoked <emphasis role="italic">before</emphasis> a tree-view item is - going to be expanded or collapsed. -</para> -<para> If the <emphasis role="italic">willReply</emphasis> argument to <xref linkend="mthConnectTreeViewEvent"/> method is true, the interpreter will wait for the reply from the event handler. The programmer <emphasis role="italic">must</emphasis> return either true or false. The programmer can prevent the expansion or collapse for the item by returning false. To allow the expansion or collapse to take place, the programmer must return true. </para> +<para> + If the <emphasis role="italic">willReply</emphasis> argument to <xref linkend="mthConnectTreeViewEvent"/> method is false, + or omitted, then the interpreter does not wait for the return from the event handler. +</para> <programlisting> <![CDATA[ @@ -9110,8 +9386,12 @@ KEYDWONEX key word is used. </para> <para> - The programmer need not return a value from the event handler and the interpreter does not wait for this return. However, - good practice would be to always return a value from an event handler. + 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 + 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> <programlisting> @@ -9147,8 +9427,11 @@ <varlistentry><term><emphasis role="bold">Return:</emphasis></term> <listitem> <para> - The interpreter does not wait for the the return from the event handler, so no return is required. Good practice would be - to always return a value from an event handler. + When <emphasis role="italic">willReply</emphasis> is true the interpreter will wait for the return from the event + handler, and the event handler must return a value. However the tree-view control ignores the actual value of the + return, so the event handler can return any value. 0 makes a good return. The interpreter does not wait for the the + return from the event handler if <emphasis role="italic">willReply</emphasis> is false or omitted. So no return is + required. Good practice would be to always return a value from an event handler. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> @@ -9372,6 +9655,369 @@ </section> <!-- End KeyDownEx Event Handler --> + +<section id="evtTreeViewSELCHANGED" xreflabel="SELCHANGED"><title>SelChanged Event Handler</title> +<indexterm><primary>TreeView class</primary><secondary>events</secondary><tertiary>SELCHANGED</tertiary></indexterm> +<para> + The event handler for the CHANGED event is invoked when the selection has changed from one item to another. +</para> +<para> + This event notification has been enhanced since the original ooDialog implementation. If the <emphasis + role="italic">willReply</emphasis> argument to the <xref linkend="mthConnectTreeViewEvent"/> 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> + +<variablelist> + <varlistentry><term><emphasis role="bold">New event handler description:</emphasis></term> + <listitem> + <para> + Whether the programmer must return a value and if the interpreter waits, or does not wait, for this return is + determined by the value of the <emphasis role="italic">willReply</emphasis> argument. If <emphasis + role="italic">willReply</emphasis> is true, the programmer must return a value from the event handler and the + interpreter waits for that reply. If <emphasis role="italic">willReply</emphasis> is false the interpreter does not + wait for a reply. + </para> + + <programlisting> + <![CDATA[ + ::method onSelChanged unguarded + use arg id, hItemOld, userOld, hItemNew, userNew, action, rxTv + + return 0 + ]]> + </programlisting> + + <variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method receives 7 arguments: + </para> + <variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The resource id of the tree-view sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>hItemOld</term> + <listitem> + <para> + The handle of the tree-view item handle that has lost the selction. This may be 0 if no item had the selection. + </para> + </listitem></varlistentry> + <varlistentry><term>userOld</term> + <listitem> + <para> + The user <link linkend="mthSetItemDataClsTreeView">data</link> object assigned to the tree-view item that lost the + selection. If no user data has been assigned to that item, of if <emphasis role="italic">hItemOld</emphasis> is 0, + this argument will be the <computeroutput>.nil</computeroutput> object. + </para> + </listitem></varlistentry> + <varlistentry><term>hItemNew</term> + <listitem> + <para> + The handle of the tree-view item handle that gained the selction. + </para> + </listitem></varlistentry> + <varlistentry><term>userNew</term> + <listitem> + <para> + The user <link linkend="mthSetItemDataClsTreeView">data</link> object assigned to the tree-view item that gained + the selection. If no user data has been assigned to that item, this argument will be the + <computeroutput>.nil</computeroutput> object. + </para> + </listitem></varlistentry> + <varlistentry><term>action</term> + <listitem> + <para> + A keyword that indicates the type of action that caused the selection to change. This will be one of the following + keywords: + </para> + <para> + <simplelist type='vert' columns='3'> + <member>KEYBOARD </member> + <member>MOUSECLICK</member> + <member>UNKNOWN </member> + </simplelist> + <variablelist> + <varlistentry><term>KEYBOARD</term> + <listitem> + <para> + By a keystroke. + </para> + </listitem></varlistentry> + <varlistentry><term>MOUSECLICK</term> + <listitem> + <para> + By a mouseclick. + </para> + </listitem></varlistentry> + <varlistentry><term>UNKNOWN</term> + <listitem> + <para> + Unknown. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term>rxTv</term> + <listitem> + <para> + The Rexx tree-view object whose underlying tree-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="mthNewTreeView"/> method. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + When the programmer used true for the <emphasis role="italic">willReply</emphasis> argument, the event handler must + return a value. However, the tree-view ignores the returned value, so any value can be used. 0 makes a good return. + If <emphasis role="italic">willReply</emphasis> is false, the event handler does not need to return a value. Good + practice would probably be to always return a value from an event handler. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Old event handler description:</emphasis></term> + <listitem> + <para> + The old style event notification is used when the programmer omits the <emphasis role="italic">willReply</emphasis> + argument in the invocation of the <xref linkend="mthConnectTreeViewEvent"/> method. The return from the event handler is + completely ignored, the interpreter does not wait for this return. + </para> + + <programlisting> + <![CDATA[ + ::method onSelChanged unguarded + use arg id, useLess + ]]> + </programlisting> + + <variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method receives 2 arguments: + </para> + <variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The resource id of the tree-view sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>useLess</term> + <listitem> + <para> + This argument is a number that has no meaning within the Rexx code. It is the value the old implementation of the + event notification sent to the event handler. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + The interpreter does not wait for the return from the event handler, so the return has no meaning. Good practice would + be to return a value anyway. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> +</variablelist> + +</section> <!-- End SELCHANGED Event Handler --> + + +<section id="evtTreeViewSELCHANGING" xreflabel="SELCHANGING"><title>SelChanging Event Handler</title> +<indexterm><primary>TreeView class</primary><secondary>events</secondary><tertiary>SELCHANGING</tertiary></indexterm> +<para> + The event handler for the CHANGING event is invoked when the selection is about to change from one item to another. +</para> +<para> + This event notification has been enhanced since the original ooDialog implementation. If the <emphasis + role="italic">willReply</emphasis> argument to the <xref linkend="mthConnectTreeViewEvent"/> method is omitted the old + implementation is used. If the argument is not omitted, the new implementation is used. Replying to the notification gives + the programmer the opportunity to cancel the change in selection. How the two event handlers work is described separately: +</para> + +<variablelist> + <varlistentry><term><emphasis role="bold">New event handler description:</emphasis></term> + <listitem> + <para> + Whether the programmer must return a value and if the interpreter waits, or does not wait, for this return is + determined by the value of the <emphasis role="italic">willReply</emphasis> argument. If <emphasis + role="italic">willReply</emphasis> is true, the programmer must return true or false from the event handler and the + interpreter waits for that reply. If <emphasis role="italic">willReply</emphasis> is false the interpreter does not + wait for a reply. + </para> + + <programlisting> + <![CDATA[ + ::method onSelChanging unguarded + use arg id, hItemOld, userOld, hItemNew, userNew, action, rxTv + + return trueOrFalse + ]]> + </programlisting> + + <variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method receives 7 arguments: + </para> + <variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The resource id of the tree-view sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>hItemOld</term> + <listitem> + <para> + The handle of the tree-view item handle that is about to lose the selction. This may be 0 if no item has the + selection. + </para> + </listitem></varlistentry> + <varlistentry><term>userOld</term> + <listitem> + <para> + The user <link linkend="mthSetItemDataClsTreeView">data</link> object assigned to the tree-view item that is about + to lose the selection. If no user data has been assigned to that item, of if <emphasis + role="italic">hItemOld</emphasis> is 0, this argument will be the <computeroutput>.nil</computeroutput> object. + </para> + </listitem></varlistentry> + <varlistentry><term>hItemNew</term> + <listitem> + <para> + The handle of the tree-view item handle that will gain the selction. + </para> + </listitem></varlistentry> + <varlistentry><term>userNew</term> + <listitem> + <para> + The user <link linkend="mthSetItemDataClsTreeView">data</link> object assigned to the tree-view item that will + gain the selection. If no user data has been assigned to that item, this argument will be the + <computeroutput>.nil</computeroutput> object. + </para> + </listitem></varlistentry> + <varlistentry><term>action</term> + <listitem> + <para> + A keyword that indicates the type of action that will cause the selection to change. This will be one of the + following keywords: + </para> + <para> + <simplelist type='vert' columns='3'> + <member>KEYBOARD </member> + <member>MOUSECLICK</member> + <member>UNKNOWN </member> + </simplelist> + <variablelist> + <varlistentry><term>KEYBOARD</term> + <listitem> + <para> + By a keystroke. + </para> + </listitem></varlistentry> + <varlistentry><term>MOUSECLICK</term> + <listitem> + <para> + By a mouseclick. + </para> + </listitem></varlistentry> + <varlistentry><term>UNKNOWN</term> + <listitem> + <para> + Unknown. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term>rxTv</term> + <listitem> + <para> + The Rexx tree-view object whose underlying tree-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="mthNewTreeView"/> method. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + When the programmer used true for the <emphasis role="italic">willReply</emphasis> argument, the event handler must + return true or false. Return true to allow the selection change. Return false to cancel the selection change. + </para> + <para> + If <emphasis role="italic">willReply</emphasis> is false, the event handler does not need to return a value. The + interpreter will not wait for the return from the event handler. Good practice would probably be to always return a + value from an event handler. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Old event handler description:</emphasis></term> + <listitem> + <para> + The old style event notification is used when the programmer omits the <emphasis role="italic">willReply</emphasis> + argument in the invocation of the <xref linkend="mthConnectTreeViewEvent"/> method. The return from the event handler is + completely ignored, the interpreter does not wait for this return. + </para> + + <programlisting> + <![CDATA[ + ::method onSelChanging unguarded + use arg id, useLess + ]]> + </programlisting> + + <variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method receives 2 arguments: + </para> + <variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The resource id of the tree-view sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>useLess</term> + <listitem> + <para> + This argument is a number that has no meaning within the Rexx code. It is the value the old implementation of the + event notification sent to the event handler. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + The interpreter does not wait for the return from the event handler, so the return has no meaning. Good practice would + be to return a value anyway. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> +</variablelist> + +</section> <!-- End SELCHANGING Event Handler --> + + </section> <!-- End EventNotification::connectTreeViewEvent() --> |
From: <mie...@us...> - 2012-11-28 03:58:00
|
Revision: 8635 http://sourceforge.net/p/oorexx/code-0/8635 Author: miesfeld Date: 2012-11-28 03:57:57 +0000 (Wed, 28 Nov 2012) Log Message: ----------- ooDialog - continue ToolTip doc. Modified Paths: -------------- docs/trunk/oodialog/en-US/tooltip.xml docs/trunk/oodialog/en-US/treeview.xml Modified: docs/trunk/oodialog/en-US/tooltip.xml =================================================================== --- docs/trunk/oodialog/en-US/tooltip.xml 2012-11-28 01:08:54 UTC (rev 8634) +++ docs/trunk/oodialog/en-US/tooltip.xml 2012-11-28 03:57:57 UTC (rev 8635) @@ -274,23 +274,23 @@ </row> <row> <entry><xref linkend="mthGetMaxTipWidth"/></entry> -<entry>x</entry> +<entry>Retrieves the maximum width for this ToolTip window.</entry> </row> <row> <entry><xref linkend="mthGetTextClsToolTip"/></entry> -<entry>x</entry> +<entry>Retrieves the text information this ToolTip control maintains about the specified tool.</entry> </row> <row> <entry><xref linkend="mthGetTipBkColor"/></entry> -<entry>x</entry> +<entry>Retrieves the background color for this ToolTip's window.</entry> </row> <row> <entry><xref linkend="mthGetTipTextColor"/></entry> -<entry>x</entry> +<entry>Retrieves the text color fot this ToolTip's window.</entry> </row> <row> <entry><xref linkend="mthTitle"/></entry> -<entry>x</entry> +<entry>Retrieves information concerning the title and icon of this ToolTip control.</entry> </row> <row> <entry><xref linkend="mthGetToolCount"/></entry> @@ -1396,61 +1396,36 @@ <indexterm><primary>ToolTip class</primary><secondary>getMaxTipWidth</secondary></indexterm> <programlisting> <![CDATA[ ->>--getMaxTipWidth(--+--------+--)--------------------------------------------->< - +--type--+ +>>--getMaxTipWidth------------------------------->< ]]> </programlisting> <para> - xx + Retrieves the maximum width for this ToolTip window. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The arguments are: + This method has no arguments. </para> - <variablelist> - <varlistentry><term>TERM</term> - <listitem> - <para> - xx - </para> - </listitem></varlistentry> - </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns a whole number value that represents the maximum ToolTip width, in pixels. If no maximum width was set + previously, this method returns -1. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + The maximum ToolTip width value does not indicate a ToolTip window's actual width. Rather, if a ToolTip string exceeds + the maximum width, the control breaks the text into multiple lines, using spaces or newline characters to determine line + breaks. If the text cannot be segmented into multiple lines, it will be displayed on a single line. The length of this + line may exceed the maximum ToolTip width. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details</emphasis></term> - <listitem> - <para> - Raises syntax errors when incorrect usage is detected. - </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> - <listitem> - <para> - This example ... -<programlisting> -<![CDATA[ - -]]> -</programlisting> - </para> - </listitem></varlistentry> </variablelist> </section> <!-- End ToolTip::getMaxTipWidth() --> @@ -1460,13 +1435,13 @@ <indexterm><primary>ToolTip class</primary><secondary>getText</secondary></indexterm> <programlisting> <![CDATA[ ->>--getText(--+--------+--)--------------------------------------------->< - +--type--+ +>>--getText(--toolHwnd--+----------+--)---------->< + +-,-toolID-+ ]]> </programlisting> <para> - xx + Retrieves the text information this ToolTip control maintains about the specified tool. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -1475,24 +1450,33 @@ The arguments are: </para> <variablelist> - <varlistentry><term>TERM</term> + <varlistentry><term>toolHwnd [required]</term> <listitem> <para> - xx + The <emphasis role="italic">toolHwnd</emphasis> and <emphasis role="italic">toolID</emphasis> arguments are the Rexx + object combination that <link linkend="sctToolIdentification">identify</link> the tool to be deleted. </para> </listitem></varlistentry> + <varlistentry><term>toolID [optional]</term> + <listitem> + <para> + The <emphasis role="italic">toolHwnd</emphasis> and <emphasis role="italic">toolID</emphasis> arguments are the Rexx + object combination that <link linkend="sctToolIdentification">identify</link> the tool to be deleted. + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + The text string for the specified tool </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + The <link linkend="sctToolIdentification">Tool Identification</link> section explains exactly how the Rexx object + combination is used to specify the tool to get the text for. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> @@ -1500,17 +1484,21 @@ <para> Raises syntax errors when incorrect usage is detected. </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example example prints to the screen the text for a tool tip where the tool is a rectangular area in a dialog: <programlisting> <![CDATA[ + say 'Text for the tool tip:' tt~getText(self, IDTOOL_DLG_RECT1) + +/* Output might be: + +Text for the tool tip: Over main dialog, top left quadrant + +*/ ]]> </programlisting> </para> @@ -1524,61 +1512,26 @@ <indexterm><primary>ToolTip class</primary><secondary>getTipBkColor</secondary></indexterm> <programlisting> <![CDATA[ ->>--getTipBkColor(--+--------+--)--------------------------------------------->< - +--type--+ +>>--getTipBkColor-------------------------------->< ]]> </programlisting> <para> - xx + Retrieves the background color for this ToolTip window. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The arguments are: + There are no arguments for this method. </para> - <variablelist> - <varlistentry><term>TERM</term> - <listitem> - <para> - xx - </para> - </listitem></varlistentry> - </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns a <xref linkend="defColorRef"/> value that represents the background color of this ToolTip window. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> - <listitem> - <para> - Additional comments. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details</emphasis></term> - <listitem> - <para> - Raises syntax errors when incorrect usage is detected. - </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> - <listitem> - <para> - This example ... -<programlisting> -<![CDATA[ - -]]> -</programlisting> - </para> - </listitem></varlistentry> </variablelist> </section> <!-- End ToolTip::getTipBkColor() --> @@ -1588,61 +1541,26 @@ <indexterm><primary>ToolTip class</primary><secondary>getTipTextColor</secondary></indexterm> <programlisting> <![CDATA[ ->>--getTipTextColor(--+--------+--)--------------------------------------------->< - +--type--+ +>>--getTipTextColor------------------------------>< ]]> </programlisting> <para> - xx + Retrieves the text color fot this ToolTip window. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The arguments are: + This method does not have any arguments. </para> - <variablelist> - <varlistentry><term>TERM</term> - <listitem> - <para> - xx - </para> - </listitem></varlistentry> - </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns a <xref linkend="defColorRef"/> value that represents the background color of this ToolTip window. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> - <listitem> - <para> - Additional comments. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details</emphasis></term> - <listitem> - <para> - Raises syntax errors when incorrect usage is detected. - </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> - <listitem> - <para> - This example ... -<programlisting> -<![CDATA[ - -]]> -</programlisting> - </para> - </listitem></varlistentry> </variablelist> </section> <!-- End ToolTip::getTipTextColor() --> @@ -1652,59 +1570,143 @@ <indexterm><primary>ToolTip class</primary><secondary>getTitle</secondary></indexterm> <programlisting> <![CDATA[ ->>--getTitle(--+--------+--)--------------------------------------------->< - +--type--+ +>>--getTitle------------------------------------->< ]]> </programlisting> <para> - xx + Retrieves information concerning the title and icon of this ToolTip control. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The arguments are: + This method takes no arguments. </para> - <variablelist> - <varlistentry><term>TERM</term> - <listitem> - <para> - xx - </para> - </listitem></varlistentry> - </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns a <computeroutput>.Directory</computeroutput> object whose indexes contain the title and icon information for + this ToolTip. Indexes are: </para> + <variablelist> + <varlistentry><term>TITLE</term> + <listitem> + <para> + The title text. + </para> + </listitem></varlistentry> + <varlistentry><term>ICON</term> + <listitem> + <para> + The ICON index will be the <xref linkend="clsImage"/> object used for the icon of this ToolTip, or one of the following + keywords if a system image is used for the icon: + </para> + <para> + <simplelist type='vert' columns='3'> + <member>NONE </member> + <member>ERROR </member> + <member>ERRORLARGE </member> + <member>INFO </member> + <member>INFOLARGE </member> + <member>WARNING </member> + <member>WARNINGLARGE</member> + </simplelist> + <variablelist> + <varlistentry><term>NONE</term> + <listitem> + <para> + No icon. + </para> + </listitem></varlistentry> + <varlistentry><term>ERROR</term> + <listitem> + <para> + Error icon. + </para> + </listitem></varlistentry> + <varlistentry><term>ERRORLARGE</term> + <listitem> + <para> + Large warning icon. + </para> + </listitem></varlistentry> + <varlistentry><term>INFO</term> + <listitem> + <para> + Info icon. + </para> + </listitem></varlistentry> + <varlistentry><term>INFOLARGE</term> + <listitem> + <para> + Large info icon. + </para> + </listitem></varlistentry> + <varlistentry><term>WARNING</term> + <listitem> + <para> + Warning icon. + </para> + </listitem></varlistentry> + <varlistentry><term>WARNINGLARGE</term> + <listitem> + <para> + Large warning icon. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term>ISKEYWORD</term> + <listitem> + <para> + True if the ICON index is a keyword, false if it is an <computeroutput>Image</computeroutput> object. + </para> + </listitem></varlistentry> + </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + The underlying Windows API for <emphasis role="italic">getTitle</emphasis> appears to be rather idiosyncratic. </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details</emphasis></term> - <listitem> <para> - Raises syntax errors when incorrect usage is detected. - </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> - <listitem> - <para> - This example ... -<programlisting> -<![CDATA[ + In testing, when setting the icon to an actual icon image, getting the icon always returns the INFOLARGE keyword, rather + than the icon image. In addition, when setting the icon to any of the LARGE keyword values, getting the icon always + returns the non-large keyword. This anomaly is mentioned in several places on the web. The following table shows this + behaviour: -]]> -</programlisting> + <table id="tblGetTitleReturns" frame="all"> <title>getTitle Anomalies</title> + <tgroup cols="2"> + <colspec colwidth="1*"/> + <colspec colwidth="1*"/> + <thead> + <row> + <entry>Actual Icon Value</entry> + <entry>getTitle() returns</entry> + </row> + </thead> + <tbody> + <row> + <entry>hIcon</entry> + <entry>INFOLARGE</entry> + </row> + <row> + <entry>INFOLARGE</entry> + <entry>INFO</entry> + </row> + <row> + <entry>WARNINGLARGE</entry> + <entry>WARNING</entry> + </row> + <row> + <entry>ERRORLARGE</entry> + <entry>ERROR</entry> + </row> + </tbody></tgroup> + </table> </para> </listitem></varlistentry> </variablelist> @@ -3666,8 +3668,8 @@ <listitem> <para> If the <xref linkend="clsResourceImage"/> class is enhanced to work with string resources (a good possibility) then this - attribute will the <computeroutput>ResourceImage</computeroutput> that contains the string resource to use for the text - |
From: <mie...@us...> - 2012-11-29 00:42:44
|
Revision: 8638 http://sourceforge.net/p/oorexx/code-0/8638 Author: miesfeld Date: 2012-11-29 00:42:39 +0000 (Thu, 29 Nov 2012) Log Message: ----------- #419 Add Tooltip control See ticket [Feature-Requests:#419] Continue work on doc for ToolTip class. Modified Paths: -------------- docs/trunk/oodialog/en-US/monthcalendar.xml docs/trunk/oodialog/en-US/tooltip.xml docs/trunk/oodialog/en-US/utilityclasses.xml docs/trunk/oodialog/en-US/windowBase.xml Modified: docs/trunk/oodialog/en-US/monthcalendar.xml =================================================================== --- docs/trunk/oodialog/en-US/monthcalendar.xml 2012-11-29 00:41:15 UTC (rev 8637) +++ docs/trunk/oodialog/en-US/monthcalendar.xml 2012-11-29 00:42:39 UTC (rev 8638) @@ -3445,5 +3445,1022 @@ </variablelist> </section> <!-- End MonthCalendar::sizeRectToMin() --> + +<section id="clsDayState" xreflabel="DayState"><title>DayState Class</title> +<indexterm><primary>DayState class</primary></indexterm> +<para> + A <computeroutput>DayState</computeroutput> object represents the state of each day in a month. It is a specialty + class used by the <xref linkend="clsMonthCalendar"/> class when the month calendar needs to reply + to the <xref linkend="evtMonthCalendarGETDAYSTATE"/> event. +</para> +<para> + Each <computeroutput>DayState</computeroutput> object contains a single value. The value encodes the state of each day + in a format understood by the <xref linkend="ovvUnderlying"/> Windows month calendar control. The + state of a single day is a binary value. I.e., on or off, true or false, special or not special, however it is + convenient for the programmer to think of. When the state of a day is on, the month calendar displays that day in + bold. +</para> + +<section id="sctMethodsDayState"><title>Method Table</title> +<para> + The following table lists the class and instance methods of the <computeroutput>DayState</computeroutput> class: + +<table id="tblMethodsDayState" frame="all"> <title>DayState Class Method Reference</title> +<tgroup cols="2"> +<colspec colwidth="1*" /> +<colspec colwidth="4*" /> +<thead> +<row> +<entry>Method</entry> +<entry>Description</entry> +</row> +</thead> +<tbody> +<row> +<entry align="center"><emphasis role="bold">Class Methods</emphasis></entry> +<entry align="center"><emphasis role="bold">Class Methods</emphasis></entry> +</row> +<row> +<entry><xref linkend="mthNewClsDayState"/></entry> +<entry>Instantiates a new <computeroutput>DayState</computeroutput> object and sets the state of each day.</entry> +</row> +<row> +<entry align="center"><emphasis role="bold">Instance Methods</emphasis></entry> +<entry align="center"><emphasis role="bold">Instance Methods</emphasis></entry> +</row> +<row> +<entry><xref linkend="mthValue"/></entry> +<entry>Returns the <emphasis role="italic">value</emphasis> of the <computeroutput>DayState</computeroutput> object.</entry> +</row> +</tbody></tgroup> +</table> +</para> +</section> + +<section id="mthNewClsDayState" xreflabel="new"><title>new (Class Method)</title> +<indexterm><primary>new</primary><secondary>DayState class</secondary></indexterm> +<indexterm><primary>DayState class</primary><secondary>new</secondary></indexterm> +<programlisting> +<![CDATA[ + + +--,-----+ + V | +>>--new(---dayNum--+--)-------------------------->< + +]]> +</programlisting> + +<para> + Instantiates a new <computeroutput>DayState</computeroutput> object and sets the state of each day. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The arguments are: + <variablelist> + <varlistentry><term>dayNum [optional]</term> + <listitem> + <para> + A single <emphasis role="italic">dayNum</emphasis> argument is the number of a day within a month whose state + should be turned <emphasis role="italic">on</emphasis>. If there are no arguments, none of the days in the month + are turned on. The arguments can repeat any number of times, but each argument must be a whole number within the + range of 1 to 32, inclusive. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + A new <computeroutput>DayState</computeroutput> object. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect arguments are detected. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example constructs a day state for an application that displays the author's birth date in a + <xref linkend="clsMonthCalendar"/> calendar control in bold. All other days of the year are displayed + without emphasis. +<programlisting> <![CDATA[ + +::method getProperDayState private + use strict arg date + + if date~orderedDate~substr(3, 2) == 07, date~orderedDate~right(2) == 14 then + return .DayState~new(14) + else + return .DayState~new + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End DayState::new() --> + +<section id="mthValue" xreflabel="value"><title>value</title> +<indexterm><primary>value</primary></indexterm> +<indexterm><primary>DayState class</primary><secondary>value</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--value---------------------------------------->< + +]]> +</programlisting> + +<para> + The <emphasis role="italic">value</emphasis> method returns the encoded value of the + <computeroutput>DayState</computeroutput> object. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + There are no arguments. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + The return is a number that encodes the state of every day within a month. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + There is probably no practical use of this method for the programmer, other than perhaps curiosity. The method is + used by the interpreter to get the encoded numerical value of a <computeroutput>DayState</computeroutput> object and + send that number to the underlying month calendar control. + </para> + <para> + For those curious, the encoding is essentially a bit field. Each bit, 1 through 31 represents the state of the + corresponding day in a month. If the bit is on, the month calendar displays that day in bold. If the bit is not on, + the day is displayed normally. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect arguments are detected. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example is for the curious and displays the bit encoding of a day state value: +<programlisting> +<![CDATA[ + + dayState = .DayState~new(1, 4, 17) + say 'dayState value:' dayState~value 'binary form:' dayState~value~d2x~x2b + + /* Output would be: + + dayState value: 65545 binary form: 00010000000000001001 + + */ +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End DayState::value() --> + +</section> <!-- End DayState Class --> + + +<section id="clsDayStates" xreflabel="DayStates"><title>DayStates Class</title> +<indexterm><primary>DayStates class</primary></indexterm> +<para> + A <computeroutput>DayStates</computeroutput> object is a sequential collection of + day <xref linkend="clsDayState"/> objects. It is a speciality class used to construct the proper reply + value for the <xref linkend="evtMonthCalendarGETDAYSTATE"/> event of the + <xref linkend="clsMonthCalendar"/> calendar control. +</para> +<para> + The primary purpose of the <computeroutput>DayStates</computeroutput> class is to supply the buffer of day states that + is used to reply to the get day state event. But, the class also has methods that allow the programmer to build a + cache of day state objects. Then during the get day state event, the programmer can request a buffer of some number of + the cached day states. +</para> + +<section id="sctMethodsDayStates"><title>Method Table</title> +<para> + The following table lists the class and instance methods of the <computeroutput>DayStates</computeroutput> class: + +<table id="tblMethodsDayStates" frame="all"> <title>DayStates Class Method Reference</title> +<tgroup cols="2"> +<colspec colwidth="1*" /> +<colspec colwidth="4*" /> +<thead> +<row> +<entry>Method</entry> +<entry>Description</entry> +</row> +</thead> +<tbody> +<row> +<entry align="center"><emphasis role="bold">Class Methods</emphasis></entry> +<entry align="center"><emphasis role="bold">Class Methods</emphasis></entry> +</row> +<row> +<entry><xref linkend="mthNewClsDayStates"/></entry> +<entry>Instantiates a new <computeroutput>DayStates</computeroutput> object with a cache of <computeroutput>DayState</computeroutput> objects.</entry> +</row> +<row> +<entry><xref linkend="mthMakeDayStateBuffer"/></entry> +<entry>Returns a buffer of the specified <computeroutput>DayState</computeroutput> objects</entry> +</row> +<row> +<entry><xref linkend="mthQuickDayStateBuffer"/></entry> +<entry>Returns a buffer constructed from the 3 <computeroutput>DayState</computeroutput> objects specified.</entry> +</row> +<row> +<entry align="center"><emphasis role="bold">Attributes</emphasis></entry> +<entry align="center"><emphasis role="bold">Attributes</emphasis></entry> +</row> +<row> +<entry><xref linkend="atrEndMonth"/></entry> +<entry>Reflects the last month in the cache of <computeroutput>DayState</computeroutput> objects.</entry> +</row> +<row> +<entry><xref linkend="atrStartMonth"/></entry> +<entry>Reflects the first month in the cache of <computeroutput>DayState</computeroutput> objects.</entry> +</row> +<row> +<entry align="center"><emphasis role="bold">Instance Methods</emphasis></entry> +<entry align="center"><emphasis role="bold">Instance Methods</emphasis></entry> +</row> +<row> +<entry><xref linkend="mthPutMonth"/></entry> +<entry>Puts a single <computeroutput>DayState</computeroutput> object in the cache.</entry> +</row> +<row> +<entry><xref linkend="mthPutYear"/></entry> +<entry>Puts an entire year of <computeroutput>DayState</computeroutput> objects in the cache.</entry> +</row> +<row> +<entry><xref linkend="mthGetDayState"/></entry> +<entry>Returns the specified <computeroutput>DayState</computeroutput> object from the cache.</entry> +</row> +<row> +<entry><xref linkend="mthGetDayStateBuffer"/></entry> +<entry>Returns a day state buffer constructed from the specified months in the cache</entry> +</row> +</tbody></tgroup> +</table> +</para> +</section> + + +<section id="mthMakeDayStateBuffer" xreflabel="makeDayStateBuffer"><title>makeDayStateBuffer (Class method)</title> +<indexterm><primary>makeDayStateBuffer</primary></indexterm> +<indexterm><primary>DayStates class</primary><secondary>makeDayStateBuffer</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--makeDayStateBuffer(--dayStates--)------------>< + +]]> +</programlisting> + +<para> + Returns a buffer of the specified day states. This buffer can be used for the return from the event handler for a + <xref linkend="evtMonthCalendarGETDAYSTATE"/> event. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The single argument is: + <variablelist> + <varlistentry><term>dayStates [required]</term> + <listitem> + <para> + An array of <xref linkend="clsDayState"/> objects. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + The return is a day states buffer. The buffer is only useful as the reply to the GETDAYSTATE event of the month + calendar control. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + The <emphasis role="italic">dayStates</emphasis> array can not be sparse. The day state objects are assumed to be + sequential by the underlying month calendar control. + </para> </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect arguments are detected. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example shows part of the implementation for a GETDAYSTATE event handler. Start with the month of the start + date requested, and then, for the number of months requested, a day state object is created and put into an array. + The <emphasis role="italic">makeDayStateBuffer</emphasis> method is invoked to get the proper buffer, which is + returned from the event handler. +<programlisting> +<![CDATA[ + +::method onGetDayState unguarded + use arg startDate, count, id, hwnd + + -- Create the array to hold the .DayState objects. + dayStates = .array~new(count) + + -- The calendar is restricted to a single year. We + -- know for our application, the month calendar always + -- requests 3 months, the partial month prior to the + -- current month showing, the current month, and the + -- partial month following the current month. + -- + -- So, if the starting month is December, it can only + -- be the December prior to January of the current + -- year. It can not be the December of this year because + -- the calendar will not display January of next year. + -- Setting the month to 0 will produce a day state with + -- no days turned on, exactly what we want. + + month = startDate~month + if month == 12 then month = 0 + + do i = 1 to count + dayStates[i] = self~getDayState(month + i - 1) + end + + buffer = .DayStates~makeDayStateBuffer(dayStates) + return buffer + + +::method getDayState private + use strict arg month + + select + when month == 1 then ds = .DayState~new(17) + when month == 2 then ds = .DayState~new(21) + when month == 3 then ds = .DayState~new + ... + otherwise ds = .DayState~new + end + -- End select + + return ds + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End DayStates::makeDayStateBuffer() --> + + +<section id="mthNewClsDayStates" xreflabel="new"><title>new (Class Method)</title> +<indexterm><primary>new</primary><secondary>DayStates class</secondary></indexterm> +<indexterm><primary>DayStates class</primary><secondary>new</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--new(--+-------------+--+---------+--)-------->< + +--startYear--+ +-,-count-+ +]]> +</programlisting> + +<para> + Instantiates a new <computeroutput>DayStates</computeroutput> object and initalizes the cache of + <xref linkend="clsDayState"/> objects. Each day state in the is initialized with the state of every day + turned off. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The arguments are: + <variablelist> + <varlistentry><term>startYear [optional]</term> + <listitem> + <para> + Specifies the starting year for the cache. The default if this argument is omitted is two years prior to the + current year. The <emphasis role="italic">startYear</emphasis> is specified as the whole number year value, + e.g., 2011, 1988, 1492, etc.. + </para> + </listitem></varlistentry> + <varlistentry><term>count [optional]</term> + <listitem> + <para> + The number of years to initialize the cache with. The default is 3 years. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + The return is a new <computeroutput>DayStates</computeroutput> object. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + The cache of day state values in a day states object is always a whole number of years in size, and is always + sequential. I.e., 12 day state values for each year. As indicated, initially the state of every day is turned off. + The <xref linkend="mthPutMonth"/> and <xref linkend="mthPutYear"/> methods are used set + the day state values in the cache to values with the state of days turned on. + </para> + <para> + The <xref linkend="mthMakeDayStateBuffer"/> and + <xref linkend="mthQuickDayStateBuffer"/> class methods can be used to obtain a day states + buffer without initializing or using a cache. + </para> </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect arguments are detected. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example instantiates a new <computeroutput>DayStates</computeroutput> object and initializes the cache to 10 + years, with the start year one year prior to the current date. It then sets the state of July 4th of every year to + on: + +<programlisting> +<![CDATA[ + + yr = (.DateTime~today~year - 1) + + dayStates = .DayStates~new(yr, 10) + + dayState = .DayState~new(4) + do 10 + dayStates~putMonth(yr, 7, dayState) + yr += 1 + end + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End DayStates::new() --> + + +<section id="mthQuickDayStateBuffer" xreflabel="quickDayStateBuffer"><title>quickDayStateBuffer (Class method)</title> +<indexterm><primary>quickDayStateBuffer</primary></indexterm> +<indexterm><primary>DayStates class</primary><secondary>quickDayStateBuffer</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--quickDayStateBuffer(--dayState1--,--dayState2--,--dayState3--)------------->< + +]]> +</programlisting> + +<para> + Returns a buffer for the 3 specified day states. This buffer can be used for the return from the event handler for a + <xref linkend="evtMonthCalendarGETDAYSTATE"/> event. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The arguments are the 3 <computeroutput>DayState</computeroutput> objects used to construct the buffer. + <variablelist> + <varlistentry><term>dayState1 [required]</term> + <listitem> + <para> + The first day state in the sequence of day states. + </para> + </listitem></varlistentry> + <varlistentry><term>dayState2 [required]</term> + <listitem> + <para> + The second day state in the sequence of day states. + </para> + </listitem></varlistentry> + <varlistentry><term>dayState3 [required]</term> + <listitem> + <para> + The third day state in the sequence of day states. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + The return is a day states buffer. The buffer is only useful as the reply to the GETDAYSTATE event of the month + calendar control. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + Normally the month calendar control is sized to only display 1 month. With this display, a week prior to the month + and a week after the month are also shown. For this situation, when the underlying month calendar requests + information on how to display individual days through the + <xref linkend="evtMonthCalendarGETDAYSTATE"/> notification, it will always request 3 months. The + <emphasis role="italic">quickDayStateBuffer</emphasis> is a convenience method for this situation, which is the most + common request. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect arguments are detected. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example shows the event handler for the GETDAYSTATE notification in an application that shows the 1st and the + 15th of each month in bold. The application always sizes the month calendar with 1 full month displayed. Because of + this, we know the count will be 3. +<programlisting> +<![CDATA[ + +::method onGetDayState unguarded + use arg startDate, count, id, hwnd + + -- All months are the same, so we can ignore the start date. + ds = .DayState~new(1, 15) + return .DayStates~quickDayStateBuffer(ds, ds, ds) + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End DayStates::quickDayStateBuffer() --> + + +<section id="atrEndMonth" xreflabel="endMonth"><title>endMonth (Attribute)</title> +<indexterm><primary>endMonth</primary></indexterm> +<indexterm><primary>DayStates class</primary><secondary>endMonth</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--endMonth------------------------------------->< + +]]> +</programlisting> + +<para> + The <emphasis role="italic">endMonth</emphasis> attribute reflects the last month in the cache of + <xref linkend="clsDayState"/> objects. Its value is a <computeroutput>DateTime</computeroutput> object + whose date is the first of the last month and last year in the cache. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">endMonth get:</emphasis></term> + <listitem> + <para> + Returns a <computeroutput>DateTime</computeroutput> object whose date is the last month in the cache. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">endMonth set:</emphasis></term> + <listitem> + <para> + The <emphasis role="italic">endMonth</emphasis> attribute can not be set by the programmer. It is set internally by + the class. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + Since the cache always contains whole years, the date of the <emphasis role="italic">endMonth</emphasis> attribute + is always going to be 12/01. The real information will be the year of the <emphasis + role="italic">endMonth</emphasis> date. I.e., if the <xref linkend="atrStartMonth"/> attribute is + 1/1/1990 and the <emphasis role="italic">endMonth</emphasis> attribute is 12/01/2010 then the cache contains 21 + complete years of <computeroutput>DayState</computeroutput> objects. + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End DayStates::endMonth() [attribute] --> + + +<section id="atrStartMonth" xreflabel="startMonth"><title>startMonth (Attribute)</title> +<indexterm><primary>startMonth</primary></indexterm> +<indexterm><primary>DayStates class</primary><secondary>startMonth</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--startMonth----------------------------------->< + +]]> +</programlisting> + +<para> + The <emphasis role="italic">startMonth</emphasis> attribute reflects the first month in the cache of + <xref linkend="clsDayState"/> objects. Its value is a <computeroutput>DateTime</computeroutput> object + whose date is the first of January of the first year in the cache. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">startMonth get:</emphasis></term> + <listitem> + <para> + Returns a <computeroutput>DateTime</computeroutput> object whose date is the first month in the cache. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">startMonth set:</emphasis></term> + <listitem> + <para> + The programmer can not set the <emphasis role="italic">startMonth</emphasis> attribute. It is set internally by the + class. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + Since the cache always contains whole years, the date of the <emphasis role="italic">startMonth</emphasis> attribute + is always going to be 1/1. The real information will be the year of the <emphasis + role="italic">startMonth</emphasis> date. I.e., if the <emphasis role="italic">startMonth</emphasis> attribute is + 1/1/2010 and the <xref linkend="atrEndMonth"/> attribute is 12/01/2011 then the cache contains 2 + complete years of <computeroutput>DayState</computeroutput> objects. + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End DayStates::startMonth() [attribute] --> + + +<section id="mthGetDayState" xreflabel="getDayState"><title>getDayState</title> +<indexterm><primary>getDayState</primary></indexterm> +<indexterm><primary>DayStates class</primary><secondary>getDayState</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--getDayState(--dateTime--)-------------------->< + +]]> +</programlisting> + +<para> + Retrieves the cached <xref linkend="clsDayState"/> object for the date specified. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The single argument is: + <variablelist> + <varlistentry><term>dateTime</term> + <listitem> + <para> + A <computeroutput>DateTime</computeroutput> object that specifies which <computeroutput>DayState</computeroutput> + object to retrieve. Only the month and the year of <emphasis role="italic">dateTime</emphasis> are relevant, the + day is ignored. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + The value returned is the <computeroutput>DayState</computeroutput> object in the cache for the date specified, or + <computeroutput>.nil</computeroutput> if there is no day state in the cache for the date. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + Normally there is no need to get specific day state objects from the cache, the programmer usually wants a <emphasis + role="italic">buffer</emphasis> of day state objects. However this method can be of use in debugging by checking + what values are actually in the cache. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example expands on the example for the <xref linkend="mthPutYear"/> method by checking the values + of the <xref linkend="atrStartMonth"/> and <xref linkend="atrEndMonth"/> day state + objects. +<programlisting> +<![CDATA[ + + dayStates = .DayStates~new(2010, 3) + dayState = .DayState~new(7, 14, 21, 28) + + do i = 2010 to 2012 + year = .DateTime~fromStandardDate(i || 0101) + + a = .array~new(12) + do j = 1 to 12 + a[j] = dayState + end + + dayStates~putYear(year, a) + end + + s = dayStates~startMonth + e = dayStates~endMonth + + say 'Start month day state value:' dayStates~getDayState(s)~value~d2x~x2b + say 'End month day state value: ' dayStates~getDayState(e)~value~d2x~x2b + +::requires 'ooDialog.cls' + +/* Output to the console would be: + +Start month day state value: 1000000100000010000001000000 +End month day state value: 1000000100000010000001000000 + + */ +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End DayStates::getDayState() --> + + +<section id="mthGetDayStateBuffer" xreflabel="getDayStateBuffer"><title>getDayStateBuffer</title> +<indexterm><primary>getDayStateBuffer</primary></indexterm> +<indexterm><primary>DayStates class</primary><secondary>getDayStateBuffer</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--getDayStateBuffer(--dateTime--,--count--)---->< + +]]> +</programlisting> + +<para> + Creates a buffer from the cached <xref linkend="clsDayState"/> objects using the specified date and + <emphasis role="italic">count</emphasis>. This buffer can be used for the return from the event handler for a + <xref linkend="evtMonthCalendarGETDAYSTATE"/> event. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The arguments are: + <variablelist> + <varlistentry><term>dateTime [required]</term> + <listitem> + <para> + A <computeroutput>DateTime</computeroutput> object whose date is used as the starting point in the cache to fetch + the <computeroutput>DayState</computeroutput> objects. + </para> + </listitem></varlistentry> + <varlistentry><term>count [required]</term> + <listitem> + <para> + The number of <computeroutput>DayState</computeroutput> objects to use in the returned buffer. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + The return is a day states buffer. The buffer is only useful as the reply to the GETDAYSTATE event of the month + calendar control. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + If some, or all, of the day state objects requested for the buffer are not in the cache, then a new + <computeroutput>DayState</computeroutput> object is create with the start of all days turned off and used. The cache + is not updated, it remains the same after the method returns. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example sets up a cache of <computeroutput>DayState</computeroutput> objects before the application dialog is + displayed. It then gets buffers from this cache during the + <xref linkend="evtMonthCalendarGETDAYSTATE"/> event to return from the event handler. +<programlisting> <![CDATA[ + +::class 'PaidHolidaysDlg' subclass ResDialog + +::method init + expose dayStates + + forward class (super) continue + + dayStates = self~createDayStateCache + self~connectMonthCalendarEvent(IDC_MC_HOLIDAYS, "GETDAYSTATE", onGetDayState) + ... + +::method onGetDayState unguarded + expose dayStates + use arg startDate, count, id, hwnd + + return dayStates~getDayStateBuffer(startDate, count) + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End DayStates::getDayStateBuffer() --> + + +<section id="mthPutMonth" xreflabel="putMonth"><title>putMonth</title> +<indexterm><primary>putMonth</primary></indexterm> +<indexterm><primary>DayStates class</primary><secondary>putMonth</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--putMonth(--dateTime--,--dayState--)---------->< + +]]> +</programlisting> + +<para> + Puts a single <xref linkend="clsDayState"/> object into the cache. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The arguments are: + <variablelist> + <varlistentry><term>dateTime [required]</term> + <listitem> + <para> + A <computeroutput>DateTime</computeroutput> object whose date specifies the month in the cache to put the + <emphasis role="italic">dayState</emphasis>. + </para> + </listitem></varlistentry> + <varlistentry><term>dayState [required]</term> + <listitem> + <para> + The <computeroutput>DayState</computeroutput> object to put in the cache. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + There is no return value from this method. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + If a day state object already exists for the month specified, it is replaced by <emphasis + role="italic">dayState</emphasis>. + </para> + <para> + If the month specified by the <emphasis role="italic">dateTime</emphasis> argument does not yet exist in the cache, + then the cache is extended to include the year specified by <emphasis role="italic">dateTime</emphasis>. The month + specified is assigned the <emphasis role="italic">dayState</emphasis> argument and all other months in the extension + are assigned a <computeroutput>DayState</computeroutput> object with a value of 0, (all days are turned off.) + </para> </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example shows how <emphasis role="italic">putMonth</emphasis> works. A + <computeroutput>DateTime</computeroutput> object with the date of 7/1/2012 is used for the month and a + <computeroutput>DayState</computeroutput> object is created with the 4th turned on. That will display July 4th 2012 + bolded. + </para> + <para> + The output shows that before <emphasis role="italic">putMonth</emphasis> is invoked, the end month of the + day states object was December 2011. After <emphasis role="italic">putMonth</emphasis> is invoked, the end month is + December 2012. Adding July 2012 to the cache extended the entire year of 2012. All months other than July will have + all days in the month turned off. +<programlisting> +<![CDATA[ + + dayStates = .DayStates~new(2010, 2) + say "Day states end month:" dayStates~endMonth~standardDate + + month = .DateTime~fromStandardDate(20120701) + dayState = .DayState~new(4) + + dayStates~putMonth(month, dayState) + + say "Day states end month:" dayStates~endMonth~standardDate + +::requires "ooDialog.cls" + +/* Output would be: + + Day states end month: 20111201 + Day states end month: 20121201 + +*/ + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End DayStates::putMonth() --> + + +<section id="mthPutYear" xreflabel="putYear"><title>putYear</title> +<indexterm><primary>putYear</primary></indexterm> +<indexterm><primary>DayStates class</primary><secondary>putYear</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--putYear(--dateTime--,--dayStates--)---------->< + +]]> +</programlisting> + +<para> + The <emphasis role="italic">putYear</emphasis> method adds a year of <xref linkend="clsDayState"/> + objects to the cache. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The arguments are: + <variablelist> + <varlistentry><term>dateTime [required]</term> + <listitem> + <para> + A <computeroutput>DateTime</computeroutput> object that specifies the year being added. Only the year portion of + the date is relevant. The day and month of the date are ignored. + </para> + </listitem></varlistentry> + <varlistentry><term>dayStates [required]</term> + <listitem> + <para> + An <computeroutput>array</computeroutput> of <computeroutput>DayState</computeroutput> objects that are the day + states for the months of the year being added. Only the indexes 1 through 12 are looked at. If the index contains + a day state object, that day state object is assigned to the corresponding month. If an index does not have a + value, then a day state object with a value of 0, (no days are turned on,) is assigned to the corresponding month. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + There is no return from this method. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + If the year specified already exists in the cache then that year is replaced by the day state objects specified int + the <emphasis role="italic">dayStates</emphasis> array. + </para> + <para> + If the year does not exist yet in the cache it is added. If adding the new year creates a gap in the sequential + order of years in the cache, then the gap is filled in using years with the state of all days turned off. In other + words, if the cache currently consists of the years 2008 through 2012 and the <emphasis + role="italic">putYear</emphasis> method is used to put the year 2016 in the cache, then the cache is also filled + with the years 2013 through 2015. Each year 2013 through 2015 have day state objects with the state of all days + turned off. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example creates a <computeroutput>DayStates</computeroutput> object with 3 years cached. In the application + that uses this, all months have the 7th, 14th, 21st, and 28th days displayed in bold. After instantiating the new + <computeroutput>DayStates</computeroutput> object, each year in the cache is updated with a + <computeroutput>DayState</computeroutput> object that turns the state of the 7th, 14th, 21st, and 28th on. + +<programlisting> +<![CDATA[ + + dayStates = .DayStates~new(2010, 3) + dayState = .DayState~new(7, 14, 21, 28) + + do i = 2010 to 2012 + year = .DateTime~fromStandardDate(i || 0101) + + a = .array~new(12) + do j = 1 to 12 + a[j] = dayState + end + + dayStates~putYear(year, a) + end + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End DayStates::putYear() --> + +</section> <!-- End DayStates Class --> + </chapter> <!-- End MonthCalendar class --> Modified: docs/trunk/oodialog/en-US/tooltip.xml =================================================================== --- docs/trunk/oodialog/en-US/tooltip.xml 2012-11-29 00:41:15 UTC (rev 8637) +++ docs/trunk/oodialog/en-US/tooltip.xml 2012-11-29 00:42:39 UTC (rev 8638) @@ -294,23 +294,23 @@ </row> <row> <entry><xref linkend="mthGetToolCount"/></entry> -<entry>x</entry> +<entry>Retrieves the number of tools this ToolTip contains.</entry> </row> <row> <entry><xref linkend="mthGetToolInfo"/></entry> -<entry>x</entry> +<entry>Retrieves the information, as a <xref linkend="clsToolInfo"/> object, that this tool tip control maintains about the specified tool.</entry> </row> <row> <entry><xref linkend="mthHasCurrentTool"/></entry> -<entry>x</entry> +<entry>Tests if this ToolTip has a current tool.</entry> </row> <row> <entry><xref linkend="mthHitTestClsToolTip"/></entry> -<entry>x</entry> +<entry>Tests a point to determine whether it is within the bounding rectangle of a tool within the window specified and, if it is, retrieves information about the tool.</entry> </row> <row> <entry><xref linkend="mthManageAtypicalTool"/></entry> -<entry>x</entry> +<entry>Initiates the management of a ToolTip tool that is a dialog control.</entry> </row> <row> <entry><xref linkend="mthNewToolRect"/></entry> @@ -1718,57 +1718,51 @@ <indexterm><primary>ToolTip class</primary><secondary>getToolCount</secondary></indexterm> <programlisting> <![CDATA[ ->>--getToolCount(--+--------+--)--------------------------------------------->< - +--type--+ +>>--getToolCount--------------------------------->< ]]> </programlisting> <para> - xx + Retrieves the number of tools this ToolTip contains. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The arguments are: + There are no arguments for this method. </para> - <variablelist> - <varlistentry><term>TERM</term> - <listitem> - <para> - xx - </para> - </listitem></varlistentry> - </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns the number of tools in the ToolTip. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + The <emphasis role="italic">getToolCount</emphasis> method in conjunction with the <xref linkend="mthEnumTools"/> method + is useful in enumerating the tools of the ToolTip. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details</emphasis></term> - <listitem> - <para> - Raises syntax errors when incorrect usage is detected. - </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> - </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example prints out information for each tool in the ToolTip: <programlisting> <![CDATA[ + do i = 1 to tt~getToolCount + toolInfo = tt~enumTools(i) + say 'Tool info hwnd: ' toolInfo~rexxHwnd + say 'Tool info id: ' toolInfo~rexxID + say 'Tool info text: ' toolInfo~text + say 'Tool info flags: ' toolInfo~flags + say 'Tool info rect: ' toolInfo~rect + say 'Tool info userData:' toolInfo~userData + say 'Tool info resource:' toolInfo~resource + say + end ]]> </programlisting> </para> @@ -1782,13 +1776,14 @@ <indexterm><primary>ToolTip class</primary><secondary>getToolInfo</secondary></indexterm> <programlisting> <![CDATA[ ->>--getToolInfo(--+--------+--)--------------------------------------------->< - +--type--+ +>>--getToolInfo(--toolHwnd--+----------+--)------>< + +-,-toolID-+ ]]> </programlisting> <para> - xx + Retrieves the information, as a <xref linkend="clsToolInfo"/> object, that this tool tip control maintains about the + specified tool. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -1797,24 +1792,34 @@ The arguments are: </para> <variablelist> - <varlistentry><term>TERM</term> + <varlistentry><term>toolHwnd [required]</term> <listitem> <para> - xx + The <emphasis role="italic">toolHwnd</emphasis> and <emphasis role="italic">toolID</emphasis> arguments are the Rexx + object combination that <link linkend="sctToolIdentification">identify</link> the tool to be deleted. </para> </listitem></varlistentry> + <varlistentry><term>toolID [optional]</term> + <listitem> + <para> + The <emphasis role="italic">toolHwnd</emphasis> and <emphasis role="italic">toolID</emphasis> arguments are the Rexx + object combination that <link linkend="sctToolIdentification">identify</link> the tool to be deleted. + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns a <computeroutput>ToolInfo</computeroutput> object whose attributes reflect the information that this ToolTip + maintains about the specified tool. On error, the <computeroutput>.nil</computeroutput> object is returned. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + The <link linkend="sctToolIdentification">Tool Identification</link> section explains exactly how the Rexx object + combination is used to specify the tool to be deleted. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> @@ -1822,21 +1827,7 @@ <para> Raises syntax errors when incorrect usage is detected. </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> - <listitem> - <para> - This example ... -<programlisting> -<![CDATA[ - -]]> -</programlisting> - </para> - </listitem></varlistentry> </variablelist> </section> <!-- End ToolTip::getToolInfo() --> @@ -1846,61 +1837,32 @@ <indexterm><primary>ToolTip class</primary><secondary>hasCurrentTool</secondary></indexterm> <programlisting> <![CDATA[ ->>--hasCurrentTool(--+--------+--)--------------------------------------------->< - +--type--+ +>>--hasCurrentTool------------------------------->< ]]> </programlisting> <para> - xx + Tests if this ToolTip has a current tool. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The arguments are: + This method has no arguments. </para> - <variablelist> - <varlistentry><term>TERM</term> - <listitem> - <para> - xx - </para> - </listitem></varlistentry> - </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Retunrs true if there is a current tool, false if there is not. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details</emphasis></term> - <listitem> - <para> - Raises syntax errors when incorrect usage is detected. - </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> - <listitem> - <para> - This example ... -<programlisting> -<![CDATA[ - -]]> -</programlisting> - </para> - </listitem></varlistentry> + In essence, this convenience method tests if the <xref linkend="mthGetCurrentToolInfo"/> method will return a + <computeroutput>ToolInof</computeroutput> object or the <computeroutput>.nil</computeroutput> object. + </para> </listitem></varlistentry> </variablelist> </section> <!-- End ToolTip::hasCurrentTool() --> @@ -1910,13 +1872,23 @@ <indexterm><primary>ToolTip class</primary><secondary>hitTest</secondary></indexterm> <programlisting> <![CDATA[ ->>--hitTest(--+--------+--)--------------------------------------------->< - +--type--+ +Form 1: + +>>--hitTest(--toolInfo--,--point--)-------------->< + +Form 2: + +>>--hitTest(--toolInfo--,--x,--y--)-------------->< + +Generic form: + +>>--hitTest(--toolInfo--,--ptToTest--)----------->< ]]> </programlisting> <para> - xx + Tests a point to determine whether it is within the bounding rectangle of a tool within the window specified and, if it + is, retrieves information about the tool. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -1925,42 +1897,84 @@ The arguments are: </para> <variablelist> - <varlistentry><term>TERM</term> + <varlistentry><term>toolInfo [required in / out]</term> <listitem> <para> - xx + A <xref linkend="clsToolInfo"/> object whose <xref linkend="atrRexxHwnd"/> attribute specifies which tool window to test. </para> + <para> + If the point tested is within a tool of the tool window, the retrieved tool information is returned in this object. + The tool info object should be instantiated using the <xref linkend="mthForHitTest"/> class method. + </para> </listitem></varlistentry> + <varlistentry><term>ptToTest [required]</term> + <listitem> + <para> + The point to test. The point is specifed in client <link linkend="defScreenCoordinates">coordinates</link> of the + window specified by the <emphasis role="italic">toolInfo</emphasis> argument. + </para> + <para> + As indicated by the syntax diagram, the point to test can be specified in two ways. Either as one argument, a <xref + linkend="clsPoint"/> object, or as two arguments, the x coordinate of the point followed by the y coordinate of the + point. + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + True if the point being tested is within the window specified, otherwise false. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> - <listitem> - <para> - Additional comments. - </para> - </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> <listitem> <para> Raises syntax errors when incorrect usage is detected. </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example gets the current cursor position and then hit tests that position for a push button tool: <programlisting> <![CDATA[ + mouse = .Mouse~new(self) + pos = mouse~getCursorPos + pbTest~screen2client(pos) + + hitTool = .ToolInfo~forHitTest(pbTest) + + say 'Using' pos + if ttTest~hitTest(hitTool, pos) then do + say 'Got hit' + say 'Tool info hwnd: ' hitTool~rexxHwnd + say 'Tool info id: ' hitTool~rexxID + say 'Tool info text: ' hitTool~text + say 'Tool info flags: ' hitTool~flags + say 'Tool info rect: ' hitTool~rect + say 'Tool info userData:' hitTool~userData + say 'Tool info resource:' hitTool~resource + say + end + else do + say 'NO hit' + say 'Tool info hwnd: ' hitTool~rexxHwnd + end + +/* Output could be for instantce: + +Got hit +Tool info hwnd: a SimpleDialog +Tool info id: a Button +Tool info text: Press Test to execute the regression suite +Tool info flags: IDISHWND SUBCLASS +Tool info rect: a Rect (0, 0, 0, 0) +Tool info userData: The NIL object +Tool info resource: The NIL object + +*/ ]]> </programlisting> </para> @@ -1974,13 +1988,14 @@ <indexterm><primary>ToolTip class</primary><secondary>manageAtypicalTool</secondary></indexterm> <programlisting> <![CDATA[ ->>--manageAtypicalTool(--+--------+--)--------------------------------------------->< - +--type--+ +>>--manageAtypicalTool(--toolObj--+-----------+--+-----------+--)-------------->< + +-,-events--+ +-,-methods-+ ]]> </programlisting> <para> - xx + Initiates the management of a ToolTip tool that is a dialog control. This is for a tool that is not the typical tool used + in a TooTip. See the remarks section for details. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -1989,9 +2004,23 @@ The arguments are: </para> <variablelist> - <varlistentry><term>TERM</term> + <varlistentry><term>toolObj [required]</term> <listitem> <para> + The tool dialog control to be managed. + </para> + </listitem></varlistentry> + <varlistentry><term>events [optional]</term> + <listitem> + <para> + An array of keywords for the ToolTip events that should invoke a method in the Rexx dialog. The array can not be + sparse. Each index in the array should contain the keyword for a ToolTip event. If an event keyword is present at an + index, then that event is connected to a method in the Rexx dialog. + </para> + </listitem></varlistentry> + <varlistentry><term>methods [optional]</term> + <listitem> + <para> xx </para> </listitem></varlistentry> Modified: docs/trunk/oodialog/en-US/utilityclasses.xml =================================================================== --- docs/trunk/oodialog/en-US/utilityclasses.xml 2012-11-29 00:41:15 UTC (rev 8637) +++ docs/trunk/oodialog/en-US/utilityclasses.xml 2012-11-29 00:42:39 UTC (rev 8638) @@ -1020,1023 +1020,6 @@ </section> -<section id="clsDayState" xreflabel="DayState"><title>DayState Class</title> -<indexterm><primary>DayState class</primary></indexterm> -<para> - A <computeroutput>DayState</computeroutput> object represents the state of each day in a month. It is a specialty - class used by the <xref linkend="clsMonthCalendar"/> class when the month calendar needs to reply - to the <xref linkend="evtMonthCalendarGETDAYSTATE"/> event. -</para> -<para> - Each <computeroutput>DayState</computeroutput> object contains a single value. The value encodes the state of each day - in a format understood by the <xref linkend="ovvUnderlying"/> Windows month calendar control. The - state of a single day is a binary value. I.e., on or off, true or false, special or not special, however it is - convenient for the programmer to think of. When the state of a day is on, the month calendar displays that day in - bold. -</para> - -<section id="sctMethodsDayState"><title>Method Table</title> -<para> - The following table lists the class and instance methods of the <computeroutput>DayState</computeroutput> class: - -<table id="tblMethodsDayState" frame="all"> <title>DayState Class Method Reference</title> -<tgroup cols="2"> -<colspec colwidth="1*" /> -<colspec colwidth="4*" /> -<thead> -<row> -<entry>Method</entry> -<entry>Description</entry> -</row> -</thead> -<tbody> -<row> -<entry align="center"><emphasis role="bold">Class Methods</emphasis></entry> -<entry align="center"><emphasis role="bold">Class Methods</emphasis></entry> -</row> -<row> -<entry><xref linkend="mthNewClsDayState"/></entry> -<entry>Instantiates a new <computeroutput>DayState</computeroutput> object and sets the state of each day.</entry> -</row> -<row> -<entry align="center"><emphasis role="bold">Instance Methods</emphasis></entry> -<entry align="center"><emphasis role="bold">Instance Methods</emphasis></entry> -</row> -<row> -<entry><xref linkend="mthValue"/></entry> -<entry>Returns the <emphasis role="italic">value</emphasis> of the <computeroutput>DayState</computeroutput> object.</entry> -</row> -</tbody></tgroup> -</table> -</para> -</section> - -<section id="mthNewClsDayState" xreflabel="new"><title>new (Class Method)</title> -<indexterm><primary>new</primary><secondary>DayState class</secondary></indexterm> -<indexterm><primary>DayState class</primary><secondary>new</secondary></indexterm> -<programlisting> -<![CDATA[ - - +--,-----+ - V | ->>--new(---dayNum--+--)-------------------------->< - -]]> -</programlisting> - -<para> - Instantiates a new <computeroutput>DayState</computeroutput> object and sets the state of each day. -</para> -<variablelist> - <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> - <listitem> - <para> - The arguments are: - <variablelist> - <varlistentry><term>dayNum [optional]</term> - <listitem> - <para> - A single <emphasis role="italic">dayNum</emphasis> argument is the number of a day within a month whose state - should be turned <emphasis role="italic">on</emphasis>. If there are no arguments, none of the days in the month - are turned on. The arguments can repeat any number of times, but each argument must be a whole number within the - range of 1 to 32, inclusive. - </para> - </listitem></varlistentry> - </variablelist> - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> - <listitem> - <para> - A new <computeroutput>DayState</computeroutput> object. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details</emphasis></term> - <listitem> - <para> - Raises syntax errors when incorrect arguments are detected. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> - <listitem> - <para> - This example constructs a day state for an application that displays the author's birth date in a - <xref linkend="clsMonthCalendar"/> calendar control in bold. All other days of the year are displayed - without emphasis. -<programlisting> <![CDATA[ - -::method getProperDayState private - use strict arg date - - if date~orderedDate~substr(3, 2) == 07, date~orderedDate~right(2) == 14 then - return .DayState~new(14) - else - return .DayState~new - -]]> -</programlisting> - </para> - </listitem></varlistentry> -</variablelist> -</section> <!-- End DayState::new() --> - -<section id="mthValue" xreflabel="value"><title>value</title> -<indexterm><primary>value</primary></indexterm> -<indexterm><primary>DayState class</primary><secondary>value</secondary></indexterm> -<programlisting> -<![CDATA[ ->>--value---------------------------------------->< - -]]> -</programlisting> - -<para> - The <emphasis role="italic">value</emphasis> method returns the encoded value of the - <computeroutput>DayState</computeroutput> object. -</para> -<variablelist> - <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> - <listitem> - <para> - There are no arguments. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> - <listitem> - <para> - The return is a number that encodes the state of every day within a month. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> - <listitem> - <para> - There is probably no practical use of this method for the programmer, other than perhaps curiosity. The method is - used by the interpreter to get the encoded numerical value of a <computeroutput>DayState</computeroutput> object and - send that number to the underlying month calendar control. - </para> - <para> - For those curious, the encoding is essentially a bit field. Each bit, 1 through 31 represents the state of the - corresponding day in a month. If the bit is on, the month calendar displays that day in bold. If the bit is not on, - the day is displayed normally. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details</emphasis></term> - <listitem> - <para> - Raises syntax errors when incorrect arguments are detected. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> - <listitem> - <para> - This example is for the curious and displays the bit encoding of a day state value: -<programlisting> -<![CDATA[ - - dayState = .DayState~new(1, 4, 17) - say 'dayState value:' dayState~value 'binary form:' dayState~value~d2x~x2b - - /* Output would be: - - dayState value: 65545 binary form: 00010000000000001001 - - */ -]]> -</programlisting> - </para> - </listitem></varlistentry> -</variablelist> -</section> <!-- End DayState::value() --> - -</section> <!-- End DayState Class --> - - -<section id="clsDayStates" xreflabel="DayStates"><title>DayStates Class</title> -<indexterm><primary>DayStates class</primary></indexterm> -<para> - A <computeroutput>DayStates</computeroutput> object is a sequential collection of - day <xref linkend="clsDayState"/> objects. It is a speciality class used to construct the proper reply - value for the <xref link... [truncated message content] |
From: <mie...@us...> - 2012-11-29 04:14:15
|
Revision: 8639 http://sourceforge.net/p/oorexx/code-0/8639 Author: miesfeld Date: 2012-11-29 04:14:10 +0000 (Thu, 29 Nov 2012) Log Message: ----------- #419 Add Tooltip control See ticket [Feature-Requests:#419] Continue work on doc for ToolTip class. Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml docs/trunk/oodialog/en-US/tooltip.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-29 00:42:39 UTC (rev 8638) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-29 04:14:10 UTC (rev 8639) @@ -7477,7 +7477,7 @@ </simplelist> </para> <variablelist> - <varlistentry><term>LINKCLICK</term> + <varlistentry id="kywToolTipLINKCLICK" xreflabel="LINKCLICK"><term>LINKCLICK</term> <listitem> <para> Requires Common Control <xref linkend="ovvComctl32"/> version 6.0 or later. @@ -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><term>POP</term> + <varlistentry id="kywToolTipLINKCLICK" xreflabel="LINKCLICK"><term>POP</term> <listitem> <para> This notification is sent when a ToolTip is about to be hidden. Modified: docs/trunk/oodialog/en-US/tooltip.xml =================================================================== --- docs/trunk/oodialog/en-US/tooltip.xml 2012-11-29 00:42:39 UTC (rev 8638) +++ docs/trunk/oodialog/en-US/tooltip.xml 2012-11-29 04:14:10 UTC (rev 8639) @@ -1995,8 +1995,15 @@ <para> Initiates the management of a ToolTip tool that is a dialog control. This is for a tool that is not the typical tool used - in a TooTip. See the remarks section for details. + in ooDialog. See the remarks section for details. </para> +<para> + The <emphasis role="italic">manageAtypicalTool</emphasis> initiates a process that monitors every window <link + linkend="ovvWindowMessages">message</link> sent to the <emphasis role="italic">toolObj</emphasis>, (which is a dialog + control.) This allows the process to relay all mouse messages to the tool and to intercept all event notifications sent by + the ToolTip to the <emphasis role="italic">toolObj</emphasis>. Why this is necessary is explained in more detail in the + remarks section. +</para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> @@ -2015,45 +2022,166 @@ <para> An array of keywords for the ToolTip events that should invoke a method in the Rexx dialog. The array can not be sparse. Each index in the array should contain the keyword for a ToolTip event. If an event keyword is present at an - index, then that event is connected to a method in the Rexx dialog. + index, then that event is connected to a method in the Rexx dialog. The valid keywords are, case is not significant: </para> + <para> + <simplelist type='vert' columns='3'> + <member>RELAY </member> + <member>NEEDTEXT </member> + <member>SHOW </member> + <member>POP </member> + <member>LINKCLICK</member> + <member>NORELAY </member> + </simplelist> + <variablelist> + <varlistentry><term>RELAY</term> + <listitem> + <para> + Causes the monitoring process to invoke the connected method in the Rexx dialog for every mouse message sent to + the dialog control. The method is invoked <emphasis role="italic">before</emphasis> the monitoring process relays + the message to the ToolTip. By default the method invoked for this keyword is <emphasis + role="italic">onRelay</emphasis>. + </para> + </listitem></varlistentry> + <varlistentry><term>NEEDTEXT</term> + <listitem> + <para> + Causes the monitoring process to intercept the <xref linkend="kywToolTipNEEDTEXT"/> event notification sent to + the dialog control, and invoke the connected method in the Rexx dialog. The notifcation is prevented from going + to the dialog control. By default the method invoked for this keyword is <emphasis + role="italic">onRelay</emphasis>. + </para> + </listitem></varlistentry> + <varlistentry><term>SHOW</term> + <listitem> + <para> + Causes the monitoring process to intercept the <xref linkend="kywToolTipSHOW"/> event notification sent to the + dialog control, and invoke the connected method in the Rexx dialog. The notifcation is prevented from going to + the dialog control. By default the method invoked for this keyword is <emphasis role="italic">onRelay</emphasis>. + </para> + </listitem></varlistentry> + <varlistentry><term>POP</term> + <listitem> + <para> + Causes the monitoring process to intercept the <xref linkend="kywToolTipPOP"/> event notification sent to the + dialog control and invoke the connected method in the Rexx dialog. The notifcation is prevented from going to + the dialog control. By default the method invoked for this keyword is <emphasis + role="italic">onRelay</emphasis>. + </para> + </listitem></varlistentry> + <varlistentry><term>LINKCLICK</term> + <listitem> + <para> + Causes the monitoring process to intercept the <xref linkend="kywToolTipLINKCLICK"/> event notification sent to + the dialog control and invoke the connected method in the Rexx dialog. The notifcation is prevented from going to + the dialog control. By default the method invoked for this keyword is <emphasis role="italic">onRelay</emphasis>. + </para> + </listitem></varlistentry> + <varlistentry><term>NORELAY</term> + <listitem> + <para> + Prevents the monitoring process from automatically forwarding the mouse messages to the ToolTip. There is no + method connection associated with this keyword. + </para> + </listitem></varlistentry> + </variablelist> + </para> </listitem></varlistentry> <varlistentry><term>methods [optional]</term> <listitem> <para> - xx + An array of alternative method names for each connected event. If the default method name is not suitable, for whatever + reason, then the programmer can supply her own name in the <emphasis role="italic">methods</emphasis> array. The + alternative method name must be at the same index in the <emphasis role="italic">methods</emphasis> array as the + event keyword's index in the <emphasis role="italic">events</emphasis> array. </para> + <para> + E.g., if at the keyword SHOW is present at index 2 in the <emphasis role="italic">events</emphasis> array and the + programmer wants to over-ride the default method name of <emphasis role="italic">onShow</emphasis>, then this can be + done by putting the alternative method name at index 2 in the <emphasis role="italic">methods</emphasis> array. There + is no requirement to put any name at index 1. That is, the <emphasis role="italic">methods</emphasis> array can be + sparse. + </para> </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns true on success, false on error. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + The ooDialog framework provides the <emphasis role="italic">manageAtypicalTool</emphasis> method to allow more advanced + usage of ToolTips. For a ToolTip to work properly, it needs two things. One, it needs to be aware of every mouse message + sent to the window that is the tool. Two, it needs to send event notifications to the owner window of the tool. </para> + <para> + In the typical use case in ooDialog, the window that the ToolTip sends the notifications to is the dialog, (where they + are handled by the Rexx dialog through the event connections.) When the SUBCLASS flag is used for the tool, the ToolTip + sets up its own internal process to monitor all the mouse messages sent to the tool window. In this typical use case, + there is no need for the <emphasis role="italic">manageAtypicalTool</emphasis> method. + </para> + <para> + However there are two basic situations that are not the typical use case. The first is when the SUBCLASS flag can not be + used. In this situation there needs to be some way to <emphasis role="italic">relay</emphasis> the mouse messages to the + ToolTip. The problem with mouse messages is that they are sent to the window the mouse is over. If the mouse messages are + sent to the dialog window, ooDialog would have no problem. It could intercept the mouse messages through event + connections and then relay the message to the ToolTip. However, when the mouse is over a dialog control, the dialog + window has no knowledge of the mouse messages. + </para> + <para> + The other situation is when the dialog window is not sent the ToolTip event notifications. If the event notifications are + sent to a dialog control, then there is no way to handle the events through connected methods in the Rexx dialog. Both of + these situations can arise when more advanced usage of ToolTips is tried. A common reason why the SUBCLASS flag can not + be used is because the application needs to take some action <emphasis role="italic">before</emphasis> the ToolTip is + aware of the mouse message. A common reason why the ToolTip event notifications can not be sent to the dialog window is + that the ToolTip was created by and is owned by a dialog control. + </para> + <para> + Two example programs are provided with the ooDialog distribution that explore the use of the <emphasis + role="italic">manageAtypicalTool</emphasis> method in these two situations. The are the + <computeroutput>samples\controls\ToolTip</computeroutput> subdirectories. One program is the + <computeroutput>manageControlTool.rex</computeroutput> example. The other is the + <computeroutput>customPositionToolTip.rex</computeroutput> example. + </para> + <para> + Note that when the <emphasis role="italic">manageAtypicalTool</emphasis> method starts the monitoring process, it + <emphasis role="italic">always</emphasis> forwards all mouse messages to the ToolTip, even if no both optional arugments + are ommitted. This is not always desirable. To prevent this, use the NORELAY keyword. + </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> <listitem> <para> - Raises syntax errors when incorrect usage is detected. + Requires Common Control <xref linkend="ovvComctl32"/> version 6.0 or later. </para> <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. + Raises syntax errors when incorrect usage is detected. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example sets up a customized ToolTip for a tree-view control and uses the <emphasis + role="italic">manageAtypicalTool</emphasis> method to allow the customization: <programlisting> <![CDATA[ + tv = self~newTreeView(IDC_TREE) + rect = tv~clientRect + + tt = self~createToolTip(IDC_TT) + + toolInfo = .ToolInfo~new(tv, 10, '', 'TRANSPARENT', rect) + tt~addToolEx(toolInfo) + + ... + + tt~manageAtypicalTool(tv, .array~of('RELAY', 'NEEDTEXT', 'SHOW')) + ]]> </programlisting> </para> |
From: <mie...@us...> - 2012-11-29 22:35:34
|
Revision: 8641 http://sourceforge.net/p/oorexx/code-0/8641 Author: miesfeld Date: 2012-11-29 22:35:29 +0000 (Thu, 29 Nov 2012) Log Message: ----------- #419 Add Tooltip control See ticket [Feature-Requests:#419] Continue work on doc for ToolTip class. Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml docs/trunk/oodialog/en-US/listview.xml docs/trunk/oodialog/en-US/tooltip.xml docs/trunk/oodialog/en-US/treeview.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-29 04:17:31 UTC (rev 8640) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-29 22:35:29 UTC (rev 8641) @@ -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="kywToolTipPOP" xreflabel="POS"><term>POP</term> + <varlistentry id="kywToolTipPOP" xreflabel="POP"><term>POP</term> <listitem> <para> This notification is sent when a ToolTip is about to be hidden. @@ -8396,7 +8396,7 @@ <programlisting> <![CDATA[ ::method onBeginDrag unguarded - use arg id, hItem, pos, treeView, userData + use arg id, hItem, pos, treeView, itemData return 0 ]]> @@ -8436,11 +8436,11 @@ linkend="mthNewTreeView"/> method. </para> </listitem></varlistentry> - <varlistentry><term>userData</term> + <varlistentry><term>itemData</term> <listitem> <para> - The user <link linkend="mthSetItemDataClsTreeView">data</link> object assigned to the tree-view item being dragged. - If no user data has been assigned, this argument will be the <computeroutput>.nil</computeroutput> object. + The item <link linkend="mthSetItemDataClsTreeView">data</link> object assigned to the tree-view item being dragged. + If no item data has been assigned, this argument will be the <computeroutput>.nil</computeroutput> object. </para> </listitem></varlistentry> </variablelist> @@ -8571,7 +8571,7 @@ <programlisting> <![CDATA[ ::method onBeginEdit unguarded - use arg id, hItem, editCtrl, treeViewCtrl, userData + use arg id, hItem, editCtrl, treeViewCtrl, itemData return zz ]]> @@ -8617,11 +8617,11 @@ valid as long as the dialog is executing. </para> </listitem></varlistentry> - <varlistentry><term>userData</term> + <varlistentry><term>itemData</term> <listitem> <para> - The user <link linkend="mthSetItemDataClsTreeView">data</link> object assigned to the tree-view item whose label is - about to be edited. If no user data has been assigned, this argument will be the + The item <link linkend="mthSetItemDataClsTreeView">data</link> object assigned to the tree-view item whose label is + about to be edited. If no item data has been assigned, this argument will be the <computeroutput>.nil</computeroutput> object. </para> </listitem></varlistentry> @@ -8643,17 +8643,17 @@ role="italic">hItem</emphasis> argument to determine which item is about the have its label edited, and checks that editing is allowed for that item. If it is, it returns true to allow the operation. If it is not, it returns false to cancel the operation and puts up a message box to inform the user. Note that the <emphasis - role="italic">userData</emphasis> argument is assigned to the <emphasis role="italic">rec</emphasis> variable in this - example, just to make it clear that the argument sent to the event handler is the user data object. In this - particular program the user data object is a record object: + role="italic">itemData</emphasis> argument is assigned to the <emphasis role="italic">rec</emphasis> variable in this + example, just to make it clear that the argument sent to the event handler is the item data object. In this + particular program the item data object is a record object: <programlisting> <![CDATA[ ::method onBeginEdit unguarded - use arg id, hItem, editCtrl, treeViewCtrl, userData + use arg id, hItem, editCtrl, treeViewCtrl, itemData - rec = userData + rec = itemData if rec~isEditable then return .true reply .false @@ -8768,7 +8768,7 @@ <programlisting> <![CDATA[ ::method onDelete unguarded - use arg, id, hItem, rxTv, userData + use arg, id, hItem, rxTv, itemData return 0 ]]> @@ -8801,11 +8801,11 @@ linkend="mthNewTreeView"/> method. </para> </listitem></varlistentry> - <varlistentry><term>userData</term> + <varlistentry><term>itemData</term> <listitem> <para> - The user <link linkend="mthSetItemDataClsTreeView">data</link> object assigned to the tree-view item that is being - deleted. If no user data has been assigned, this argument will be the <computeroutput>.nil</computeroutput> object. + The item <link linkend="mthSetItemDataClsTreeView">data</link> object assigned to the tree-view item that is being + deleted. If no item data has been assigned, this argument will be the <computeroutput>.nil</computeroutput> object. </para> </listitem></varlistentry> </variablelist> @@ -8900,7 +8900,7 @@ <programlisting> <![CDATA[ ::method onEndEdit unguarded - use arg id, hItem, text, treeViewCtrl, userData + use arg id, hItem, text, treeViewCtrl, itemData return trueOrFalse ]]> @@ -8940,11 +8940,11 @@ linkend="mthNewListView"/> method. </para> </listitem></varlistentry> - <varlistentry><term>userData</term> + <varlistentry><term>itemData</term> <listitem> <para> - The user <link linkend="mthSetItemDataClsTreeView">data</link> object assigned to the tree-view item whose label - was edited. If no user data has been assigned, this argument will be the <computeroutput>.nil</computeroutput> + The item <link linkend="mthSetItemDataClsTreeView">data</link> object assigned to the tree-view item whose label + was edited. If no item data has been assigned, this argument will be the <computeroutput>.nil</computeroutput> object. </para> </listitem></varlistentry> @@ -8970,14 +8970,14 @@ <![CDATA[ ::method onEndEdit unguarded - use arg id, itemIndex, text, treeViewCtrl, userData + use arg id, itemIndex, text, treeViewCtrl, itemData if text == .nil then return .false if self~isValidPart(text) then do reply .true - rec = userData + rec = itemData oldPartNo = rec~partNo rec~partNo = text self~updateRecord(oldPartNo, rec) @@ -9292,7 +9292,7 @@ <programlisting> <![CDATA[ ::method onGetInfoTip unguarded - use arg id, hItem, text, maxLen, userData + use arg id, hItem, text, maxLen, itemData return infoText ]]> @@ -9334,11 +9334,11 @@ role="italic">maxLen</emphasis> characters. </para> </listitem></varlistentry> - <varlistentry><term>userData</term> + <varlistentry><term>itemData</term> <listitem> <para> - The user <link linkend="mthSetItemDataClsTreeView">data</link> associated with the tree-view item that the info tip is - for. If no user data has been associated with the item, then this argument will be the + The item <link linkend="mthSetItemDataClsTreeView">data</link> associated with the tree-view item that the info tip is + for. If no item data has been associated with the item, then this argument will be the <computeroutput>.nil</computeroutput> object. </para> </listitem></varlistentry> @@ -9356,7 +9356,7 @@ <varlistentry><term><emphasis role="bold">Example</emphasis></term> <listitem> <para> - In the following example, the user data associated with the tree-view item tht the info tip is for, is inspected to see + In the following example, the item data associated with the tree-view item that the info tip is for, is inspected to see if it is the string: '...' If it is, then a info tip is displayed, otherwise no tip is displayed. <programlisting> @@ -9364,9 +9364,9 @@ ::method onGetInfoTip unguarded expose tv - use arg id, hItem, text, maxLen, userData + use arg id, hItem, text, maxLen, itemData - if userData == '...' then return 'There are too many books to list' + if itemData == '...' then return 'There are too many books to list' else return '' ]]> </programlisting> @@ -9711,7 +9711,7 @@ <listitem> <para> The user <link linkend="mthSetItemDataClsTreeView">data</link> object assigned to the tree-view item that lost the - selection. If no user data has been assigned to that item, of if <emphasis role="italic">hItemOld</emphasis> is 0, + selection. If no item data has been assigned to that item, of if <emphasis role="italic">hItemOld</emphasis> is 0, this argument will be the <computeroutput>.nil</computeroutput> object. </para> </listitem></varlistentry> @@ -9725,7 +9725,7 @@ <listitem> <para> The user <link linkend="mthSetItemDataClsTreeView">data</link> object assigned to the tree-view item that gained - the selection. If no user data has been assigned to that item, this argument will be the + the selection. If no item data has been assigned to that item, this argument will be the <computeroutput>.nil</computeroutput> object. </para> </listitem></varlistentry> @@ -9891,7 +9891,7 @@ <listitem> <para> The user <link linkend="mthSetItemDataClsTreeView">data</link> object assigned to the tree-view item that is about - to lose the selection. If no user data has been assigned to that item, of if <emphasis + to lose the selection. If no item data has been assigned to that item, of if <emphasis role="italic">hItemOld</emphasis> is 0, this argument will be the <computeroutput>.nil</computeroutput> object. </para> </listitem></varlistentry> @@ -9905,7 +9905,7 @@ <listitem> <para> The user <link linkend="mthSetItemDataClsTreeView">data</link> object assigned to the tree-view item that will - gain the selection. If no user data has been assigned to that item, this argument will be the + gain the selection. If no item data has been assigned to that item, this argument will be the <computeroutput>.nil</computeroutput> object. </para> </listitem></varlistentry> Modified: docs/trunk/oodialog/en-US/listview.xml =================================================================== --- docs/trunk/oodialog/en-US/listview.xml 2012-11-29 04:17:31 UTC (rev 8640) +++ docs/trunk/oodialog/en-US/listview.xml 2012-11-29 22:35:29 UTC (rev 8641) @@ -335,7 +335,7 @@ </row> <row> <entry><xref linkend="mthGetItemDataClsListView"/></entry> -<entry>Retrieves the user data associated with the specified list-view item.</entry> +<entry>Retrieves the item data associated with the specified list-view item.</entry> </row> <row> <entry><xref linkend="mthGetItemInfo"/></entry> @@ -459,7 +459,7 @@ </row> <row> <entry><xref linkend="mthRemoveItemDataClsListView"/></entry> -<entry>Removes and returns the user data associated with the specified list-view item.</entry> +<entry>Removes and returns the item data associated with the specified list-view item.</entry> </row> <row> <entry><xref linkend="mthRemoveExtendedStyle"/></entry> @@ -515,7 +515,7 @@ </row> <row> <entry><xref linkend="mthSetItemDataClsListView"/></entry> -<entry>Sets the user data associated for the specified list-view item.</entry> +<entry>Sets the item data associated for the specified list-view item.</entry> </row> <row> <entry><xref linkend="mthSetItemPos"/></entry> @@ -2762,11 +2762,11 @@ </para> <para> The <xref linkend="mthSortItems"/> method is used to do custom sorting of list-view items. The sorting is dependent on - the user data <link linkend="mthSetItemDataClsListView">item</link> being set for each list-view item. In addition, the + the item data <link linkend="mthSetItemDataClsListView">item</link> being set for each list-view item. In addition, the <emphasis role="italic">sortItems</emphasis> method can be used to signal the ooDialog framework to use native internal - code for the sorting. For the internal sort to work, the user data item must be a + code for the sorting. For the internal sort to work, the item data item must be a <computeroutput>LvFullRow</computeroutput> object. The returned object from <emphasis role="italic">getFullRow</emphasis> - can be set as the user data item to allow the interanl sorting. When invoking <emphasis + can be set as the item data to allow the interanl sorting. When invoking <emphasis role="italic">setItemData</emphasis> with a <computeroutput>LvFullRow</computeroutput> object as the argument, the internal house keeping that the ooDialog framework needs to do for internal sorts is done automatically. However, if the returned full row object is instead used to insert or add a new item into the list-view, this internal house keeping may @@ -3036,7 +3036,7 @@ </programlisting> <para> - Gets the user data associated with the specified list-view item. + Gets the item data associated with the specified list-view item. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -3048,7 +3048,7 @@ <varlistentry><term>index [required]</term> <listitem> <para> - The zero-based index of the item to retrieve the user data from. + The zero-based index of the item to retrieve the item data from. </para> </listitem></varlistentry> </variablelist> @@ -3056,7 +3056,7 @@ <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - Returns the user data associated with the specified item, or the <computeroutput>.nil</computeroutput> object if + Returns the item data associated with the specified item, or the <computeroutput>.nil</computeroutput> object if there is no data associated with the item. </para> </listitem></varlistentry> @@ -4670,7 +4670,70 @@ </variablelist> </section> <!-- End ListView::modifyColumnPX() --> +<section id="mthModifyItem" xreflabel="modifyItem"><title>modifyItem</title> +<indexterm><primary>modifyItem</primary></indexterm> +<indexterm><primary>ListView class</primary><secondary>modifyItem</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--modifyItem(--+--------+--)--------------------------------------------->< + +--type--+ +]]> +</programlisting> +<para> + xx +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The arguments are: + </para> + <variablelist> + <varlistentry><term>TERM</term> + <listitem> + <para> + xx + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + xx + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + Additional comments. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect usage is detected. + </para> + <para> + Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example ... +<programlisting> +<![CDATA[ + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End ListView::modifyItem() --> + + <section id="mthNext" xreflabel="next"><title>next</title> <indexterm><primary>next</primary> <secondary>ListView class</secondary></indexterm> @@ -4975,6 +5038,83 @@ </variablelist> </section> +<section id="mthRemoveExtendedStyle" xreflabel="removeExtendedStyle"><title>removeExtendedStyle</title> +<indexterm><primary>removeExtendedStyle</primary></indexterm> +<programlisting> +<![CDATA[ + +--------------------+ + V | +>>-aListControl~removeExtendedStyle(--"----+-BORDERSELECT-----+--"--)------->< + +-CHECKBOXES-------+ + +-DOUBLEBUFFER-----+ + +-FLATSB-----------+ + +-FULLROWSELECT----+ + +-GRIDLINES--------+ + +-HEADERDRAGDROP---+ + +-INFOTIP----------+ + +-LABELTIP---------+ + +-MULTIWORKAREAS---+ + +-ONECLICKACTIVATE-+ + +-REGIONAL---------+ + +-SIMPLESELECT-----+ + +-SUBITEMIMAGES----+ + +-TRACKSELECT------+ + +-TWOCLICKACTIVATE-+ + +-UNDERLINECOLD----+ + +-UNDERLINEHOT-----+ + +]]> +</programlisting> + +<para>The <computeroutput>removeExtendedStyle</computeroutput> method removes +one or more extended <link linkend="varListControlExtendedStyles">styles</link> of +a List-View control. +</para> +<variablelist> +<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> +<listitem><para>The only argument is: +<variablelist> +<varlistentry><term>style</term> +<listitem><para>The extended style(s) to be removed. This is one or more of the +styles listed in the syntax diagram, separated by blanks. For an explanation +of the different styles, refer to the +<xref linkend="mthAddExtendedStyle"/> method. +</para></listitem></varlistentry> +</variablelist> +</para></listitem></varlistentry> +<varlistentry><term><emphasis role="bold">Return value:</emphasis></term> +<listitem><para>The return values are: +<variablelist> +<varlistentry><term>0</term> +<listitem><para>Success. +</para></listitem></varlistentry> +<varlistentry><term>-1</term> +<listitem><para>An (internal) problem with the control's window handle. +</para></listitem></varlistentry> +<varlistentry><term>-3</term> +<listitem><para>The style argument did not contain any of the extended style +keywords. +</para></listitem></varlistentry> +</variablelist> +</para></listitem></varlistentry> +<varlistentry><term><emphasis role="bold">Example:</emphasis></term> +<listitem><para>The following example removes the check box style from the list +view. +<programlisting> +<![CDATA[ + + listView = self~newListView(IDC_LIST) + if listView == .nil then return + + listView~removeExtendedStyle("CHECKBOXES") + +]]> +</programlisting> +</para></listitem></varlistentry> +</variablelist> +</section> + + <section id="mthRemoveItemDataClsListView" xreflabel="removeItemData"><title>removeItemData</title> <indexterm><primary>removeItemData</primary><secondary>ListView class</secondary></indexterm> <indexterm><primary>ListView class</primary><secondary>removeItemData</secondary></indexterm> @@ -4986,7 +5126,7 @@ </programlisting> <para> - Removes and returns the user data associated with the specified list-view item. + Removes and returns the item data associated with the specified list-view item. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -5006,7 +5146,7 @@ <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - Returns the user data value associated with the specified item, or <computeroutput>.nil</computeroutput> if there is + Returns the item data value associated with the specified item, or <computeroutput>.nil</computeroutput> if there is no data associated with the item. </para> </listitem></varlistentry> @@ -5088,82 +5228,6 @@ </section> <!-- End ListView::removeItemData() --> -<section id="mthRemoveExtendedStyle" xreflabel="removeExtendedStyle"><title>removeExtendedStyle</title> -<indexterm><primary>removeExtendedStyle</primary></indexterm> -<programlisting> -<![CDATA[ - +--------------------+ - V | ->>-aListControl~removeExtendedStyle(--"----+-BORDERSELECT-----+--"--)------->< - +-CHECKBOXES-------+ - +-DOUBLEBUFFER-----+ - +-FLATSB-----------+ - +-FULLROWSELECT----+ - +-GRIDLINES--------+ - +-HEADERDRAGDROP---+ - +-INFOTIP----------+ - +-LABELTIP---------+ - +-MULTIWORKAREAS---+ - +-ONECLICKACTIVATE-+ - +-REGIONAL---------+ - +-SIMPLESELECT-----+ - +-SUBITEMIMAGES----+ - +-TRACKSELECT------+ - +-TWOCLICKACTIVATE-+ - +-UNDERLINECOLD----+ - +-UNDERLINEHOT-----+ - -]]> -</programlisting> - -<para>The <computeroutput>removeExtendedStyle</computeroutput> method removes -one or more extended <link linkend="varListControlExtendedStyles">styles</link> of -a List-View control. -</para> -<variablelist> -<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> -<listitem><para>The only argument is: -<variablelist> -<varlistentry><term>style</term> -<listitem><para>The extended style(s) to be removed. This is one or more of the -styles listed in the syntax diagram, separated by blanks. For an explanation -of the different styles, refer to the -<xref linkend="mthAddExtendedStyle"/> method. -</para></listitem></varlistentry> -</variablelist> -</para></listitem></varlistentry> -<varlistentry><term><emphasis role="bold">Return value:</emphasis></term> -<listitem><para>The return values are: -<variablelist> -<varlistentry><term>0</term> -<listitem><para>Success. -</para></listitem></varlistentry> -<varlistentry><term>-1</term> -<listitem><para>An (internal) problem with the control's window handle. -</para></listitem></varlistentry> -<varlistentry><term>-3</term> -<listitem><para>The style argument did not contain any of the extended style -keywords. -</para></listitem></varlistentry> -</variablelist> -</para></listitem></varlistentry> -<varlistentry><term><emphasis role="bold">Example:</emphasis></term> -<listitem><para>The following example removes the check box style from the list -view. -<programlisting> -<![CDATA[ - - listView = self~newListView(IDC_LIST) - if listView == .nil then return - - listView~removeExtendedStyle("CHECKBOXES") - -]]> -</programlisting> -</para></listitem></varlistentry> -</variablelist> -</section> - <section id="mthRemoveStyleClsListView" xreflabel="removeStyle"><title>removeStyle</title> <indexterm><primary>removeStyle</primary> <secondary>ListView class</secondary></indexterm> @@ -6059,7 +6123,7 @@ </programlisting> <para> - Sets the user data associated with the specified list-view item. + Sets the item data associated with the specified list-view item. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -6099,9 +6163,9 @@ number of ways. One specific use is in the <xref linkend="mthSortItems"/> method. </para> <para> - For the <emphasis role="italic">sortItems</emphasis> method to work, every list-view item must have the user data item - set. When <emphasis role="italic">sortItems</emphasis> is invoked to use the internal ooDialog framework to do the - sorting, the user data item must be a <xref linkend="clsLvFullRow"/> object. + For the <emphasis role="italic">sortItems</emphasis> method to work, every list-view item must have the item data set. + When <emphasis role="italic">sortItems</emphasis> is invoked to use the internal ooDialog framework to do the sorting, + the item data object must be a <xref linkend="clsLvFullRow"/> object. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> @@ -6532,7 +6596,7 @@ associate a data value with each list-view item. </para> <para> - The specifics on the user data value and what the programmer needs to do are dependent on the type of sort specified. See + The specifics on the item data value and what the programmer needs to do are dependent on the type of sort specified. See the relevant section below for a Rexx sort or an internal sort. </para> </listitem></varlistentry> @@ -6592,7 +6656,7 @@ <para> The return must be a whole number. Less than 0 places the first list item before the second item, greater than 0 places the first item after the second. Return 0 if the two items are equivalent. The programmer determines what number - to return based on the 2 user data values passed to the method. + to return based on the 2 item data values passed to the method. </para> </listitem></varlistentry> </variablelist> @@ -6601,11 +6665,11 @@ <listitem> <para> When an internal sort is used, the work of the sort is done in the native API implementation code. In essence, within - the ooDialog framework. To use this sort, the user data assigned to each list-view item must be a <xref - linkend="clsLvFullRow"/> object. The user data can be assigned to each item either through the <xref + the ooDialog framework. To use this sort, the item data assigned to each list-view item must be a <xref + linkend="clsLvFullRow"/> object. The item data can be assigned to each item either through the <xref linkend="mthSetItemDataClsListView"/> method, or during the <link linkend="mthNewClsLvFullRow">instantiation</link> of the <computeroutput>LvFullRow</computeroutput> object. The sort will not work correctly if any item in the list-view does not - have a <computeroutput>LvFullRow</computeroutput> object assigned as its user data value. + have a <computeroutput>LvFullRow</computeroutput> object assigned as its item data value. </para> <para> The sort is performed on the text of the item, or the text of the subitems of the item. By default, the sort is an @@ -6684,7 +6748,7 @@ ... -- As each full row object is instantiated, the last argument -- is set to .true to indicate the full row object should be - -- set as the user data of the list-view item: + -- set as the item data of the list-view item: rows[i] = .LvFullRow~new(lvi, lvsi1, lvsi2, lvsi3, .true) @@ -7071,25 +7135,175 @@ </variablelist> </section> -<section id="clsLvFullRow" xreflabel="LvFullRow"><title>LvFullRow Class</title> -<indexterm><primary>LvFullRow class</primary></indexterm> + +<section id="clsLvCustomDrawSimple" xreflabel="LvCustomDrawSimple"><title>LvCustomDrawSimple Class</title> +<indexterm><primary>LvCustomDrawSimple class</primary></indexterm> <para> - A <computeroutput>LvFullRow</computeroutput> object is used in ooDialog to represent a list-view item and all subitems - of that item. A <computeroutput>LvFullRow</computeroutput> object is composed of a <xref linkend="clsLvItem"/> object whose - attributes reflect the list-view item and zero or more <xref linkend="clsLvSubItem"/> objects that reflect the subitems of - the list-view item in the <link linkend="ovvUnderlying">underlying</link> list-view. + A <computeroutput>LvCustomDrawSimple</computeroutput> object is used when a <link + linkend="clsListView">ListView</link> control is registered for <emphasis role="italic">simple</emphasis> <link + linkend="clsCustomDraw">custom</link> draw. A <computeroutput>LvCustomDrawSimple</computeroutput> object is passed to the + CUSTOMDRAW event handler. It supplies both information to the event handler and returns information back to the Windows + control. The attributes of the object convey the information both ways. </para> <para> - Normally, the subitems of a list-view item are only thought about when the list-view is in report view. However, once added - to an item, the subitems exist whatever view the list-view is in. A full row object can be used to add or insert items - along with all the subitems of the item, or to query information about an item and its subitems. + When the ooDialog framework receives information from the Windows custom draw control, it instantiates a + <computeroutput>LvCustomDrawSimple</computeroutput>object, assigns values to the attributes of the object, and sends the + object to the Rexx dialog's event handler. The programmer uses the assigned values to determine what action to take and + then assigns values to the object's attributes to convey information back to the Windows control. The + <computeroutput>LvCustomDrawSimple</computeroutput> object is specific to the <computeroutput>ListView</computeroutput> + class. Other ooDialog controls that support custom draw have their own class that performs a similar function, but whose + attributes are specific to that control. For instance, the <link linkend="clsTreeView">TreeView</link> class uses the <link + linkend="clsTvCustomDrawSimple">TvCustomDrawSimple</link> for its CUSTOMDRAW event handler. </para> -<section id="sctMethodsLvFullRow"><title>Method Table</title> +<section id="evtListViewCustomDraw" xreflabel="List-view CustomDraw Event Handler"><title>CustomDraw Event Handler</title> +<indexterm><primary>ListView Event</primary><secondary>CUSTOMDRAW</secondary></indexterm> +<indexterm><primary>custom draw</primary><secondary>list-view control</secondary></indexterm> <para> - The following table lists the class and instance methods of the <computeroutput>LvFullRow</computeroutput> class: + When the list-view control is registered for <xref linkend="sctSimpleCustomDraw"/> custom draw, the event handler is + invoked when the draw stage is item prepaint. Depending on the response from the event handler to the item prepaint + notification, the event handler will also be invoked when the draw stage is subitem prepaint. For simple custom draw, the + ooDialog framework handles the other draw stages internally. It makes the appropriate response to the dialog control so + that the dialog control will send the item prepaint notifications. It is then up to the programmer to request that the + control send the subitem prepaint notifcations. +</para> +<para> + The single argument passed to the event handler is a <computeroutput>LvCustomDrawSimple</computeroutput> object. The event + handler examines the values of the attributes of the object to determine the information sent by the underlying list-view + control. The event handler then assigns values to the object that specify how the list-view control should draw the item, + or subitem. Finally, the programmer returns true to have the updated information passed on to the list-view, or false to + have the list-view draw the item as it normally would. +</para> -<table id="tblMethodsLvFullRow" frame="all"> <title>LvFullRow Class Method Reference</title> +<programlisting> +<![CDATA[ +::method onCustomDraw unguarded + use arg lvcdSimple + + return boolean +]]> +</programlisting> + +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method receives 1 argument: + </para> + <variablelist> + <varlistentry><term>lvcdSimple</term> + <listitem> + <para> + A <computeroutput>LvCustomDrawSimple</computeroutput> object whose attributes are used to convey information back and + forth between the underlying list-view control and the event handler. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + Return true to indicate that the attributes in the <computeroutput>LvCustomDrawSimple</computeroutput> object are to be + used by the list-view when drawing the item or subitem. Return false to indicate the list-view should draw the item + itself. Returning false is the equivalent of using the <xref linkend="cnstCDRF_DODEFAULT"/> value for the response to the + list-view. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + The key to using custom draw is to examine the attributes of the <computeroutput>LvCustomDrawSimple</computeroutput> + object sent as the argument to the event handler to determine which item is about to be drawn, and then set attributes in + the object to customize the drawing of that item. + </para> + <para> + As an example, say the goal was to shade every other row in the list-view when in report mode. The event handler will be + invoked before each item is to be painted. The programmer would examine the <xref linkend="atrItem"/> attrbute to + determine if it was an odd or even row. If the row was even, the color attributes, <xref linkend="atrClrTextBk"/> and + <xref linkend="atrClrText"/>, would be set to the desired colors to shade the row. The <xref linkend="atrReplyLV"/> + attribute would be set to a response value that indicates to the list-view is to use the information in the object to + draw the item, and the event handler would return true. If the row was odd, the event handler would simply return false + to indicate that the list-view should draw the item itself. The following code snippet demonstrates this: + +<programlisting> +<![CDATA[ + +::method init + expose rowYellow + + forward class (super) continue + + self~customDraw + self~customDrawControl(IDC_LV_CUSTOM, 'ListView', onCustomDraw) + + rowYellow = self~RGB(245, 245, 127) + ... + +::method onCustomDraw unguarded + expose rowYellow + use arg cdInfo + + item = cdInfo~item + + if (item // 2) == 0 then do + cdInfo~clrText = self~CLR_DEFAULT + cdInfo~clrTextBk = rowYellow + cdInfo~reply = self~CDRF_NOTIFYITEMDRAW + return .true + end + else do + return .false + end + +]]> +</programlisting> + + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example</emphasis></term> + <listitem> + <para> + The following example is an expansion of the example in the remarks section. It has a list-view that has check boxes. If + an item is checked then a new font is set for that row, along with different colors. Othewise, alternating rows are + shaded with a different color: +<programlisting> +<![CDATA[ + +::method onCustomDraw unguarded + expose list textRed textBlack textBlue rowGreen rowLiteBlue rowYellow checkedFont + use arg cdInfo + + item = cdInfo~item + + if list~isChecked(item) then do + cdInfo~clrText = textBlue + cdInfo~clrTextBk = rowLiteBlue + cdInfo~font = checkedFont + end + else if (item // 2) == 0 then do + cdInfo~clrText = textRed + cdInfo~clrTextBk = rowYellow + end + else do + cdInfo~clrText = textBlack + cdInfo~clrTextBk = rowGreen + end + + cdInfo~reply = self~CDRF_NEWFONT + return .true + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End CustomDraw Event Handler --> + +<section id="sctMethodsLvCustomDrawSimple"><title>Method Table</title> +<para> + The following table lists the class and instance methods of the <computeroutput>LvCustomDrawSimple</computeroutput> class: + +<table id="tblMethodsLvCustomDrawSimple" frame="all"> <title>LvCustomDrawSimple Class Method Reference</title> <tgroup cols="2"> <colspec colwidth="1*"/> <colspec colwidth="4*"/> @@ -7101,108 +7315,171 @@ </thead> <tbody> <row> -<entry align="center"><emphasis role="bold">Class</emphasis></entry> -<entry align="center"><emphasis role="bold">Methods</emphasis></entry> +<entry align="center"><emphasis role="bold">Class Methods</emphasis></entry> +<entry align="center"><emphasis role="bold">Class Methods</emphasis></entry> </row> <row> -<entry><xref linkend="mthNewClsLvFullRow"/></entry> -<entry>Instantiates a new <computeroutput>LvFullRow</computeroutput> object.</entry> +<entry><link linkend="mthNewClsLvCustomDrawSimple">new</link></entry> +<entry>The Rexx programmer can not instantiate a <computeroutput>LvCustomDrawSimple</computeroutput>object, the ooDialog framework instantiates these objects</entry> </row> <row> -<entry align="center"><emphasis role="bold">Instance</emphasis></entry> -<entry align="center"><emphasis role="bold">Methods</emphasis></entry> +<entry align="center"><emphasis role="bold">Attribute Methods</emphasis></entry> +<entry align="center"><emphasis role="bold">Attribute Methods</emphasis></entry> </row> +<row> +<entry><xref linkend="atrClrText"/> </entry> +<entry>Reflects a custom color that the text of the list-view item should be drawn with.</entry> +</row> +<row> +<entry><xref linkend="atrClrTextBk"/> </entry> +<entry>Reflects a custom color that the text background of the list-view itme should be drawn with.</entry> +</row> +<row> +<entry><xref linkend="atrDrawStage"/> </entry> +<entry>Reflects the draw <link linkend="sctCustomDrawOverview">stage</link> of the current paint cycle.</entry> +</row> +<row> +<entry><xref linkend="atrFont"/> </entry> +<entry>Reflects a custom font that the list-view should use for the text.</entry> +</row> +<row> +<entry><xref linkend="atrIDLV"/> </entry> +<entry>Reflects the resource ID of the list-view control sending the custom draw event notification message.</entry> +</row> +<row> +<entry><xref linkend="atrItem"/> </entry> +<entry>Reflects the 0-based index of the list-view item that needs to be drawn.</entry> +</row> +<row> +<entry><xref linkend="atrItemDataClsLvCustomDrawSimple"/></entry> +<entry>Reflects the <emphasis role="italic">item data</emphasis> for the list-view item that needs to be drawn.</entry> +</row> +<row> +<entry><xref linkend="atrReplyLV"/> </entry> +<entry>Reflects the <link linkend="sctConstantsClsCustomDraw">CDRF_*</link> response value that is used to reply to the event notification.</entry> +</row> +<row> +<entry><xref linkend="atrSubItem"/> </entry> +<entry>Reflects the index of the subitem that needs to be drawn.</entry> +</row> </tbody></tgroup> </table> </para> </section> -<section id="mthNewClsLvFullRow" xreflabel="new"><title>new (Class Method)</title> -<indexterm><primary>new</primary><secondary>LvFullRow class</secondary></indexterm> -<indexterm><primary>LvFullRow class</primary><secondary>new</secondary></indexterm> +<section id="mthNewClsLvCustomDrawSimple" xreflabel="new"><title>new (Class Method)</title> +<indexterm><primary>new</primary><secondary>LvCustomDrawSimple class</secondary></indexterm> +<indexterm><primary>LvCustomDrawSimple class</primary><secondary>new</secondary></indexterm> <programlisting> <![CDATA[ - +--------------+ - V | ->>--new(--item--+--------------+--)-------------->< - +--,--subItem--+ +>>--new------------------------------------------>< + ]]> </programlisting> <para> - Instantiates a new <computeroutput>LvFullRow</computeroutput> object. + The <computeroutput>LvCustomDrawSimple</computeroutput> class can not be instantiated by the Rexx programmer. When + needed, the ooDialog framework instantiates a <computeroutput>LvCustomDrawSimple</computeroutput> object and passes + it to the dialog's custom draw <link linkend="evtListViewCustomDraw">event</link> handler. </para> +</section> <!-- End LvCustomDrawSimple::new() --> + +<section id="atrClrText" xreflabel="clrText"><title>clrText (Attribute)</title> +<indexterm><primary>clrText</primary></indexterm> +<indexterm><primary>LvCustomDrawSimple class</primary><secondary>clrText</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--clrText----------------------------------------------------->< + +>>--clrText-=-varName------------------------------------------->< + +]]> +</programlisting> + +<para> + Reflects a custom color that the text of the list-view item should be drawn with. This attribute is information sent back + to the list-view control. +</para> <variablelist> - <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <varlistentry><term><emphasis role="bold">clrText get:</emphasis></term> <listitem> <para> - The arguments are: - <variablelist> - <varlistentry><term>item [required]</term> - <listitem> - <para> - A <link linkend="clsLvItem">LvItem</link> object that specifies the attributes of the list-view item being added. - </para> - </listitem></varlistentry> - <varlistentry><term>subItem [optional]</term> - <listitem> - <para> - A <link linkend="clsLvSubItem">LvSubItem</link> object that specifies the attributes of a subitem of the list-view - item being added. The argument can repeat has many times as needed to specify all the subitems of the item. The - subitems are added to the item in the order of the arguments to the <emphasis role="italic">new</emphasis> method. - </para> - <para> - <emphasis role="bold">Note:</emphasis> The very last argument can optionally be <computeroutput>.true</computeroutput> - or <computeroutput>.false</computeroutput> to signal that the <computeroutput>LvFullRow</computeroutput> object - itself is to be assigned as the user data value of the list-view items. This usage is explained in the remarks - section. - </para> - </listitem></varlistentry> - </variablelist> + This is a set-only attribute, it is information to be sent back to the list-view control. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <varlistentry><term><emphasis role="bold">clrText set:</emphasis></term> <listitem> <para> - Returns the new <computeroutput>LvFullRow</computeroutput> object. + Set this attribute to the color value for the text of the item. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Each subitem argument must be specified. If a subitem is omitted and a subitem argument follows it, a syntax - condition is raised. That is, if a subitem is specified, its preceding subitem must not have been omitted. These - statements are acceptable: - + To construct the proper color value use the <xref linkend="mthRGB"/> method of the + <computeroutput>CustomDraw</computeroutput> class. The <xref linkend="cnstCLR_DEFAULT"/> value can also be used to have + the item text be drawn in the default list-view color. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect usage is detected. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + In this example snippet of code the <emphasis role="italic">clrText</emphasis> attribute is set to a reddish color and + the background color is set to a yellowish color: <programlisting> <![CDATA[ - row = .LvFullRow~new(item) - row = .LvFullRow~new(item, si1, si2) - row = .LvFullRow~new(item, si1, si2, si3) + + cdInfo~clrText = self~RGB(247, 7, 59) + cdInfo~clrTextBk = self~RGB(245, 245, 127) + ]]> </programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End LvCustomDrawSimple::clrText() [attribute] --> - These statements will raise a syntax codition: - +<section id="atrClrTextBk" xreflabel="clrTextBk"><title>clrTextBk (Attribute)</title> +<indexterm><primary>clrTextBk</primary></indexterm> +<indexterm><primary>LvCustomDrawSimple class</primary><secondary>clrTextBk</secondary></indexterm> <programlisting> <![CDATA[ - row = .LvFullRow~new(item, , si2) - row = .LvFullRow~new(item, si1, , si3) +>>--clrTextBk----------------------------------------------------->< + +>>--clrTextBk-=-varName------------------------------------------->< + ]]> </programlisting> +<para> + Reflects a custom color that the text background of the list-view itme should be drawn with. This attribute is information + sent back to the list-view control. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">clrTextBk get:</emphasis></term> + <listitem> + <para> + This is a set-only attribute, it is information to be sent back to the list-view control. </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">clrTextBk set:</emphasis></term> + <listitem> <para> - In addition to specifying <computeroutput>LvSubItem</computeroutput> objects, the last argument can be either true or - false. Recall that the list-view control allows the programmer to attach a user data value to any or all of the list-view - items. The last argument can be true to specify that the <computeroutput>LvFullRow</computeroutput> object being - instantiated should be set as the user data value for the list-view item the <computeroutput>LvFullRow</computeroutput> - object represents. + Set this attribute to a custom color that should be used for the text background when the item is drawn. </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> <para> - This feature is really only of use if the full row object is used to add or insert an item into the list-view. If the - full row object is not to be used to add an item to the list-view, then there is no reason to use the last argument of - true or false. + To construct the proper color value use the <xref linkend="mthRGB"/> method of the + <computeroutput>CustomDraw</computeroutput> class. The <xref linkend="cnstCLR_DEFAULT"/> value can also be used to have + the item text background drawn in the default list-view color. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> @@ -7214,141 +7491,286 @@ <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example shows a method that creates an array of list-view full rows from NFL football player data. The array is - later used to insert the rows into a list-view control. + In this example snippet of code the <emphasis role="italic">clrText</emphasis> attribute is set to a reddish color and + the background color is set to a yellowish color: <programlisting> <![CDATA[ -::method getPlayers private + cdInfo~clrText = self~RGB(247, 7, 59) + cdInfo~clrTextBk = self~RGB(245, 245, 127) - players = .NFLPlayer~playersFromDataSource("nflPlayers.txt") +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End LvCustomDrawSimple::clrTextBk() [attribute] --> - self~masterList = .MasterPlayerList~new(players) +<section id="atrDrawStage" xreflabel="drawStage"><title>drawStage (Attribute)</title> +<indexterm><primary>drawStage</primary></indexterm> +<indexterm><primary>LvCustomDrawSimple class</primary><secondary>drawStage</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--drawStage----------------------------------------------------->< - playerRows = .array~new(players~items) - do i = 1 to players~items - j = i - 1 - p = players[i] - lvi = .LvItem~new(j, , p~name, , p) - lvsi1 = .LvSubItem~new(j, 1, p~team) - lvsi2 = .LvSubItem~new(j, 2, p~position) - lvsi3 = .LvSubItem~new(j, 3, p~rating) +>>--drawStage-=-varName------------------------------------------->< - r = .LvFullRow~new(lvi, lvsi1, lvsi2, lvsi3) - playerRows[i] = r +]]> +</programlisting> + +<para> + Reflects the draw <link linkend="sctCustomDrawOverview">stage</link> of the current paint cycle. This attribute is + information sent from the list-view control. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">drawStage get:</emphasis></term> + <listitem> + <para> + Returns the draw stage constant value as sent by the list-view control. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">drawStage set:</emphasis></term> + <listitem> + <para> + This is a get-only attribute. It is information sent from the list-view control and can not be changed. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + In <link linkend="sctSimpleCustomDraw">simple</link> custom draw, the ooDialog framework handles many of draw stage + notifications internaly and the event handler only gets invoked for 2 of the draw stages. Because of this, the draw stage + value will always be either <xref linkend="cnstCDDS_ITEMPREPAINT"/> or <xref linkend="cnstCDDS_SUBITEMPREPAINT"/>. In + addtion, the value will only be CDDS_SUBITEMPREPAINT if the programmer has requested subitem notifications by setting + the <xref linkend="atrReplyLV"/> attribute to <xref linkend="cnstCDRF_NOTIFYSUBITEMDRAW"/> in response to an item prepaint + notification. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect usage is detected. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example is from a program that uses a custom font and color for the entire row, if the item is checked. If not + checked then it uses custom draw for each subitem. The draw stage will either be CDDS_ITEMPREPAINT or + CDDS_SUBITEMPREPAINT. If it is CDDS_ITEMPREPAINT, then the event hander determines if the item is checked. + </para> + <para> + When the item is checked, the event handler sets the custom color and font. Then, because it does not return + CDRF_NOTIFYSUBITEMDRAW in the response, the list-view draws the entire row in the custom color and font, and does + <emphasis role="italic">not</emphasis> send any subitem notifications. When the item is not checked, CDRF_NOTIFYSUBITEM + is set in the response and this causes the list-view to send event notifications for each subitem: + +<programlisting> +<![CDATA[ + + ... + + if cdInfo~drawStage == self~CDDS_ITEMPREPAINT then do + if list~isChecked(item) then do + cdInfo~clrText = textBlue + cdInfo~clrTextBk = rowLiteBlue + cdInfo~font = checkedFont + cdInfo~reply = self~CDRF_NEWFONT + end + else do + cdInfo~reply = self~CDRF_NOTIFYSUBITEMDRAW + end + return .true end - return playerRows + ... - ]]> </programlisting> </para> </listitem></varlistentry> </variablelist> -</section> <!-- End LvFullRow::new() --> +</section> <!-- End LvCustomDrawSimple::drawStage() [attribute] --> -<section id="mthAddSubItem" xreflabel="addSubItem"><title>addSubItem</title> -<indexterm><primary>addSubItem</primary></indexterm> -<indexterm><primary>LvFullRow class</primary><secondary>addSubItem</secondary></indexterm> +<section id="atrFont" xreflabel="font"><title>font (Attribute)</title> +<indexterm><primary>font</primary></indexterm> +<indexterm><primary>LvCustomDrawSimple class</primary><secondary>font</secondary></indexterm> <programlisting> <![CDATA[ ->>--addSubItem(--+--------+--)--------------------------------------------->< - +--type--+ +>>--font----------------------------------------------------->< + +>>--font-=-varName------------------------------------------->< + ]]> </programlisting> <para> - xx + Reflects a custom font that the list-view should use for the text. This attribute is information sent back to the list-view + control. </para> <variablelist> - <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <varlistentry><term><emphasis role="bold">font get:</emphasis></term> <listitem> <para> - The arguments are: - <variablelist> - <varlistentry><term>TERM</term> - <listitem> - <para> - xx - </para> - </listitem></varlistentry> - </variablelist> + This is a set-only attribute, it is information to be sent back to the list-view control. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <varlistentry><term><emphasis role="bold">font set:</emphasis></term> <listitem> <para> - xx + Set this attribute to the <xref linkend="defHandle"/> of a font to used for the text of the item. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + To have the font drawn in the default font of the list-view simply do not set the <emphasis role="italic">font</emphasis> + attribute to anything. For example, if the color for the font should be changed, but not the font itself, then the + programmer should not set this attribute. </para> + <para> + Use the <xref linkend="mthCreateFontEx"/> method to get the handle of a font. Microsoft recommends that the response code + when a new font is to be used include <xref linkend="cnstCDRF_NEWFONT"/> value. If the programmer also needs subitem + notifications and is changing the font, then the CDRF_NEWFONT code should be combined with the <xref + linkend="cnstCDRF_NOTIFYSUBITEMDRAW"/> value. The <xref linkend="mthOrClsDlgUtil"/> method of the + <computeroutput>DlgUtil</computeroutput> class can be used to combine the values. + </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> <listitem> <para> Raises syntax errors when incorrect usage is detected. </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. + This example shows the <emphasis role="italic">font</emphasis> attribute being set and the response codes for new font + and subitem notify being combined: +<programlisting> +<![CDATA[ + + checkedFont = self~createFontEx("Courier New", 10) + + ... + + item = cdInfo~item + + if list~isChecked(item) then do + cdInfo~clrText = self~RGB( 17, 5, 250) + cdInfo~clrTextBk = self~RGB(115, 245, 186) + cdInfo~font = checkedFont + cdInfo~reply = .DlgUtil~or(self~CDRF_NEWFONT, self~CDRF_NOTFYSUBITEMDRAW) + end + + ... + +]]> +</programlisting> </para> </listitem></varlistentry> +</variablelist> +</section> <!-- End LvCustomDrawSimple::font() [attribute] --> + +<section id="atrIDLV" xreflabel="id"><title>id (Attribute)</title> +<indexterm><primary>id</primary></indexterm> +<indexterm><primary>LvCustomDrawSimple class</primary><secondary>id</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--id----------------------------------------------------->< + +>>--id-=-varName------------------------------------------->< + +]]> +</programlisting> + +<para> + Reflects the resource ID of the list-view control sending the custom draw event notification message. This attribute is + information sent from the list-view control. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">id get:</emphasis></term> + <listitem> + <para> + Returns the numeric <xref linkend="defResourceId"/> of the list-view control that sent the custom draw event + notification. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">id set:</emphasis></term> + <listitem> + <para> + This is a get-only attribute. It is information sent from the list-view control and can not be changed. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect usage is detected. + </para> + </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example uses custom draw with a list-view and a tree-view. It uses the same event handler, <emphasis + role="italic">onCustomDraw</emphasis> for both controls and then use the <emphasis role="italic">id</emphasis> attribute + to determine which control has sent the event notification: <programlisting> <![CDATA[ + self~customDraw + self~customDrawControl(IDC_LV_STATS, 'ListView', onCustomDraw) + self~customDrawControl(IDC_TV_PLAYERS, 'TreeView', onCustomDraw) + + ... + +::method onCustomDraw unguarded + use arg customDrawInfo + + if customDrawInfo~ID == .constDir[IDC_LV_STATS] then + return self~customDrawStats(customDrawInfo) + else + return self~customDrawPlayers(customDrawInfo) + ]]> </programlisting> </para> </listitem></varlistentry> </variablelist> -</section> <!-- End LvFullRow::addSubItem() --> +</section> <!-- End LvCustomDrawSimple::id() [attribute] --> -<section id="mthItem" xreflabel="item"><title>item</title> +<section id="atrItem" xreflabel="item"><title>item (Attribute)</title> <indexterm><primary>item</primary></indexterm> -<indexterm><primary>LvFullRow class</primary><secondary>item</secondary></indexterm> +<indexterm><primary>LvCustomDrawSimple class</primary><secondary>item</secondary></indexterm> <programlisting> <![CDATA[ ->>--item(--+--------+--)--------------------------------------------->< - +--type--+ +>>--item----------------------------------------------------->< + +>>--item-=-varName------------------------------------------->< + ]]> </programlisting> <para> - xx + Reflects the 0-based index of the list-view item that needs to be drawn. This attribute is information sent from the + list-view control. </para> <variablelist> - <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <varlistentry><term><emphasis role="bold">item get:</emphasis></term> <listitem> <para> - The arguments are: - <variablelist> - <varlistentry><term>TERM</term> - <listitem> - <para> - xx - </para> - </listitem></varlistentry> - </variablelist> + Returns the item index that the event notifications is for. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <varlistentry><term><emphasis role="bold">item set:</emphasis></term> <listitem> <para> - xx + This is a get-only attribute. It is information sent from the list-view control and can not be changed. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + Use th... [truncated message content] |
From: <mie...@us...> - 2012-12-01 02:10:45
|
Revision: 8645 http://sourceforge.net/p/oorexx/code-0/8645 Author: miesfeld Date: 2012-12-01 02:10:42 +0000 (Sat, 01 Dec 2012) Log Message: ----------- ooDialog doc - continue incremental update Modified Paths: -------------- docs/trunk/oodialog/en-US/listview.xml docs/trunk/oodialog/en-US/tooltip.xml docs/trunk/oodialog/en-US/userInput.xml Modified: docs/trunk/oodialog/en-US/listview.xml =================================================================== --- docs/trunk/oodialog/en-US/listview.xml 2012-11-30 00:14:57 UTC (rev 8644) +++ docs/trunk/oodialog/en-US/listview.xml 2012-12-01 02:10:42 UTC (rev 8645) @@ -8037,11 +8037,18 @@ <section id="clsLvItem" xreflabel="LvItem"><title>LvItem Class</title> <indexterm><primary>LvItem class</primary></indexterm> <para> - A <computeroutput>LvItem</computeroutput> object represents a single item in a list-view control. List-view items have - an icon, a label, a current state, and an application-defined value. The attributes of the - <computeroutput>LvItem</computeroutput> object reflect the values the icon, label, state, etc., for the list-view - item. + A <computeroutput>LvItem</computeroutput> object represents a single item in a list-view control. List-view items can have + a label, an icon, a current state, an application-defined value, a group ID, a set of columns to display in Tile view, + column format definitions, a state icon, and an overlay icon. The attributes of the <computeroutput>LvItem</computeroutput> + object reflect the values of the label, icon, state, etc., for the list-view item. </para> +<para> + Note that ooDialog does not currently support some of the newer features in list-views. The + <computeroutput>LvItem</computeroutput> class is part of the first steps to enhance ooDialog to support all the list-view + features. The <computeroutput>LvItem</computeroutput> class has support for attributes that will become important in an + enhanced <xref linkend="clsListView"/> class, but are not currently relevant. Support for list-view groups, Tile view, and + columns, is part of a planned enhancement. +</para> <section id="sctMethodsLvItem"><title>Method Table</title> <para> @@ -8059,6 +8066,10 @@ </thead> <tbody> <row> +<entry><link linkend="sctLvItemConstantMethods">Constant Methods</link></entry> +<entry>The <computeroutput>LvItem</computeroutput> class provides several <emphasis role="italic">constant</emphasis> values through the <computeroutput>::constant</computeroutput>directive.</entry> +</row> +<row> <entry align="center"><emphasis role="bold">Class Methods</emphasis></entry> <entry align="center"><emphasis role="bold">Class Methods</emphasis></entry> </row> @@ -8070,11 +8081,100 @@ <entry align="center"><emphasis role="bold">Attribute Methods</emphasis></entry> <entry align="center"><emphasis role="bold">Attribute Methods</emphasis></entry> </row> +<row> +<entry><xref linkend="atrColumnFormatsClsLvi"/></entry> +<entry></entry> +</row> +<row> +<entry><xref linkend="atrColumnsClsLvi"/></entry> +<entry></entry> +</row> +<row> +<entry><xref linkend="atrGroupIDClsLvi"/></entry> +<entry></entry> +</row> +<row> +<entry><xref linkend="atrImageIndexClsLvi"/></entry> +<entry></entry> +</row> +<row> +<entry><xref linkend="atrIndentClsLvi"/></entry> +<entry></entry> +</row> +<row> +<entry><xref linkend="atrIndexClsLvi"/></entry> +<entry></entry> +</row> +<row> +<entry><xref linkend="atrItemDataClsLvi"/></entry> +<entry></entry> +</row> +<row> +<entry><xref linkend="atrItemStateClsLvi"/></entry> +<entry></entry> +</row> +<row> +<entry><xref linkend="atrItemStateMaskClsLvi"/></entry> +<entry></entry> +</row> +<row> +<entry><xref linkend="atrMaskClsLvi"/></entry> +<entry></entry> +</row> +<row> +<entry><xref linkend="atrOverlayImageIndexClsLvi"/></entry> +<entry></entry> +</row> +<row> +<entry><xref linkend="atrStateImageIndexClsLvi"/></entry> +<entry></entry> +</row> +<row> +<entry><xref linkend="atrTextClsLvi"/></entry> +<entry></entry> +</row> </tbody></tgroup> </table> </para> </section> +<section id="sctLvItemConstantMethods"><title>Constant Methods</title> +<indexterm><primary>constant methods</primary><secondary>LvItem class</secondary></indexterm> +<indexterm><primary>LvItem class</primary><secondary>constant methods</secondary></indexterm> +<para> + The <computeroutput>LvItem</computeroutput> class provides the following <emphasis role="italic">constant</emphasis> + values through the use of the <computeroutput>::constant</computeroutput> directive. +</para> +<table id="tblConstantsLvItem" frame="all"> <title>LvItem Class Constant Reference</title> +<tgroup cols="2"> +<colspec colwidth="1*" /><colspec colwidth="3*" /> +<thead> +<row> +<entry>Constant Symbol</entry> +<entry>Description</entry> +</row> +</thead> +<tbody> +<row> +<entry>GROUPIDCALLBACK</entry> +<entry>A group ID index value that indicates the list-view control should send the GETDISPINFO notification message to retrieve the item's group index.</entry> +</row> +<row> +<entry>GROUPIDNONE</entry> +<entry>A group ID value that indicates the list-view item does not belong to a group.</entry> +</row> +<row> +<entry>IMAGECALLBACK</entry> +<entry>An index value for the item's icon in the control's image list that indicates the list-view control should send the GETDISPINFO notification message to retrieve the item's icon index when it needs to display the image.</entry> +</row> +<row> +<entry>IMAGENONE</entry> +<entry>An index value for the item's icon in the control's image list that indicates the list-view item does not have an icon.</entry> +</row> +</tbody></tgroup> +</table> +</section> + <section id="mthNewClsLvItem" xreflabel="new"><title>new (Class Method)</title> <indexterm><primary>new</primary><secondary>LvItem class</secondary></indexterm> <indexterm><primary>LvItem class</primary><secondary>new</secondary></indexterm> @@ -8083,7 +8183,7 @@ >>--new(--+--------+--+-------+--+-------------+--+-------+--+------------+----> +--indx--+ +-,-txt-+ +-,-imageIndx-+ +-,-msk-+ +-,-itemData-+ ->---+------------+-+---------------+-+----------+-+-----------+-+--------+--)--->< +>---+------------+-+---------------+-+----------+-+-----------+-+--------+--)-->< +-,-itmState-+ +-,-itmStateMsk-+ +-,-indent-+ +-,-groupID-+ +-,-cols-+ ]]> </programlisting> @@ -8091,9 +8191,13 @@ <para> Instantiates a new <computeroutput>LvItem</computeroutput> object. <computeroutput>LvItem</computeroutput> objects are used in some <link linkend="clsListView">Listview</link> methods such as <link - linkend="mthAddFullRow">addFullRow</link>. It is anticipated that future versions of ooDialog will make more use of + linkend="mthAddFullRow">addFullRow</link>. It is anticipated that future enhancements of ooDialog will make more use of <computeroutput>LvItem</computeroutput> objects. </para> +<para> + Some of the uses for <computeroutput>LvItem</computeroutput> objects are to set or retrieve some, or all, of the + information the underlying list-view control maintains for each list-view item. +</para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> @@ -8103,31 +8207,111 @@ <varlistentry><term>indx [optional]</term> <listitem> <para> - Sets the <xref linkend="atrIndexClsLvi"/> attribute of this list-view item. + The zero-based index of this item. The argument can not be less than 0. If this arugment is omitted it defaults to 0. + The <emphasis role="italic">indx</emphasis> argument sets the <xref linkend="atrIndexClsLvi"/> attribute of this + list-view item. </para> + <para> + Note that depending on the use of this list-view item, the ooDialog framework may modify the index attribute. For + instance if the <computeroutput>LvItem</computeroutput> is contained in a <xref linkend="clsFullRow"/> object and the + row is added to a list-view, the ooDialog framework will adjust the <emphasis role="italic">index</emphasis> attribute + to reflect the actual index of the added item. + </para> </listitem></varlistentry> <varlistentry><term>txt [optional]</term> <listitem> <para> - Sets the <xref linkend="atrTextClsLvi"/> attribute of this list-view item. + Sets the text, or label, for this list-view item. The <emphasis role="italic">txt</emphasis> argument sets the <xref + linkend="atrTextClsLvi"/> attribute of this list-view item. </para> </listitem></varlistentry> <varlistentry><term>imageIndex [optional]</term> <listitem> <para> - Sets the <xref linkend="atrImageIndexClsLvi"/> attribute of this list-view item. + The zero-based index of the item's icon in the control's <link linkend="mthSetImageListClsListView">image</link> list. + This applies to both the large and small image list. The <emphasis role="italic">imageIndex</emphasis> argument can + also be one of the following <computeroutput>LvItem</computeroutput> constants. If this argument is omitted, the + default is IMAGENONE: </para> + <para> + <simplelist type='vert' columns='3'> + <member>IMAGECALLBACK</member> + <member>IMAGENONE </member> + </simplelist> + <variablelist> + <varlistentry><term>IMAGECALLBACK</term> + <listitem> + <para> + Indicates the list-view control should send the GETDISPINFO notification message to retrieve the icon index for the + item. + </para> + </listitem></varlistentry> + <varlistentry><term>IMAGENONE</term> + <listitem> + <para> + The item does not have an icon. This is the default if this argument omitted. + </para> + </listitem></varlistentry> + </variablelist> + </para> + <para> + The <emphasis role="italic">imageIndex</emphasis> argument sets the <xref linkend="atrImageIndexClsLvi"/> attribute of + this list-view item. + </para> </listitem></varlistentry> <varlistentry><term>msk [optional]</term> <listitem> <para> - Sets the <xref linkend="atrImageIndexClsLvi"/> attribute of this list-view item. + A list of blank separate keywords that specify which attributes of this <computeroutput>LvItem</computeroutput> object + contain data to be set or which attriubtes are being requested. In general, the ooDialog framework will try to set the <xref + linkend="atrMaskClsLvi"/> attribute correctly without the programmer having to worry about this argument. As each + attribute of the <computeroutput>LvItem</computeroutput> object is set, the appropriate keyword is added to the + <emphasis role="italic">mask</emphasis> attribute. However, if this object is going to be used to retrieve information + about the underlying list-view item, the ooDialog framwork has no way to know what attributes the programmer wishes to + retrieve. For this use of the <computeroutput>LvItem</computeroutput> object, the programmer should set the mask to the + value she wants. </para> + <para> + The <emphasis role="italic">msk</emphasis> argument can have zero or more of the following keywords, case is not + significant: + </para> + <para> + <simplelist type='vert' columns='3'> + <member></member> + <member></member> + <member></member> + </simplelist> + <variablelist> + <varlistentry><term>T1</term> + <listitem> + <para> + text + </para> + </listitem></varlistentry> + <varlistentry><term>T2</term> + <listitem> + <para> + text + </para> + </listitem></varlistentry> + <varlistentry><term>T3</term> + <listitem> + <para> + text + </para> + </listitem></varlistentry> + </variablelist> + </para> + <para> + The <emphasis role="italic">msk</emphasis> argument sets the <xref linkend="atrMaskClsLvi"/> attribute of this + list-view item. + </para> </listitem></varlistentry> <varlistentry><term>itemData[optional]</term> <listitem> <para> - Sets the <xref linkend="atrImageIndexClsLvi"/> attribute of this list-view item. + The <emphasis role="italic">itemData</emphasis> argument sets the <xref linkend="atrItemDataClsLvi"/> attribute of this + list-view item. </para> </listitem></varlistentry> <varlistentry><term>itemState [optional]</term> @@ -8145,14 +8329,46 @@ <varlistentry><term>indent [optional]</term> <listitem> <para> - Sets the <xref linkend="atrImageIndexClsLvi"/> attribute of this list-view item. + The number of image widths to indent the item. A single indentation equals the width of an item image. Therefore, the + value 1 indents the item by the width of one image, the value 2 indents by two images, and so on. If this argument is + omitted, the indent is set to 0. The <emphasis role="italic">indent</emphasis>argument sets the <xref + linkend="atrIndentClsLvi"/> attribute of this list-view item. </para> </listitem></varlistentry> <varlistentry><term>groupID [optional]</term> <listitem> <para> - Sets the <xref linkend="atrImageIndexClsLvi"/> attribute of this list-view item. + Requires Common Control <xref linkend="ovvComctl32"/> version 6.0 or later. </para> + <para> + The group ID this item belongs to, or one of the following <computeroutput>LvItem</computeroutput> constants. If this + argument is omitted, the default is the GROUPIDNONE constant: + </para> + <para> + <simplelist type='vert' columns='3'> + <member>GROUPIDCALLBACK</member> + <member>GROUPIDNONE </member> + </simplelist> + <variablelist> + <varlistentry><term>GROUPIDCALLBACK</term> + <listitem> + <para> + Indicates the list-view control should send the GETDISPINFO notification message to retrieve the group index of the + item. + </para> + </listitem></varlistentry> + <varlistentry><term>GROUPIDNONE</term> + <listitem> + <para> + The item does not belong to a group. If you omit this argument, this is the default + </para> + </listitem></varlistentry> + </variablelist> + </para> + <para> + The <emphasis role="italic">groupID</emphasis> argument sets the <xref linkend="atrGroupIDClsLvi"/> attribute of this + list-view item. + </para> </listitem></varlistentry> <varlistentry><term>cols [optional]</term> <listitem> @@ -8162,7 +8378,8 @@ <para> The <emphasis role="italic">cols</emphasis> argument must be an array of subitem indexes. The indexes in the array specify which columns are displayed for this item, in <emphasis role="italic">Tile</emphasis> view, and the order of - those columns. + those columns. The array can not be sparse. The <emphasis role="italic">cols</emphasis> argument sets the <xref + linkend="atrColumnsClsLvi"/> attribute of this list-view item. </para> </listitem></varlistentry> </variablelist> Modified: docs/trunk/oodialog/en-US/tooltip.xml =================================================================== --- docs/trunk/oodialog/en-US/tooltip.xml 2012-11-30 00:14:57 UTC (rev 8644) +++ docs/trunk/oodialog/en-US/tooltip.xml 2012-12-01 02:10:42 UTC (rev 8645) @@ -3263,11 +3263,11 @@ </row> <row> <entry><link linkend="atrRexxHwnd">rexxHwnd</link></entry> -<entry>Reflects the Rexx object from which the first part of the 2-part system <link linkend="sctToolIdentification">identification</link> for a tool is derived from.</entry> +<entry>Reflects the Rexx object from which the first part of the 2-part system <link linkend="sctToolIdentification">identification</link> for a tool is derived.</entry> </row> <row> <entry><link linkend="atrRexxID">rexxID</link></entry> -<entry>Reflects the Rexx object from which the second part of the 2-part system <link linkend="sctToolIdentification">identification</link> for a tool is derived from.</entry> +<entry>Reflects the Rexx object from which the second part of the 2-part system <link linkend="sctToolIdentification">identification</link> for a tool is derived.</entry> </row> <row> <entry><link linkend="atrText">text</link></entry> @@ -3904,7 +3904,7 @@ <para> Reflects the Rexx object from which the first part of the 2-part system <link - linkend="sctToolIdentification">identification</link> for a tool is derived from. + linkend="sctToolIdentification">identification</link> for a tool is derived. </para> <variablelist> <varlistentry><term><emphasis role="bold">rexxHwnd get:</emphasis></term> @@ -3945,7 +3945,7 @@ <para> Reflects the Rexx object from which the second part of the 2-part system <link - linkend="sctToolIdentification">identification</link> for a tool is derived from. + linkend="sctToolIdentification">identification</link> for a tool is derived. </para> <variablelist> <varlistentry><term><emphasis role="bold">rexxID get:</emphasis></term> Modified: docs/trunk/oodialog/en-US/userInput.xml =================================================================== --- docs/trunk/oodialog/en-US/userInput.xml 2012-11-30 00:14:57 UTC (rev 8644) +++ docs/trunk/oodialog/en-US/userInput.xml 2012-12-01 02:10:42 UTC (rev 8645) @@ -1012,7 +1012,7 @@ </programlisting> </para> -<section id="rtnMessageDialog"><title>MessageDialog</title> +<section id="rtnMessageDialog" xreflabel="MessageDialog"><title>MessageDialog</title> <indexterm><primary>MessageDialog</primary></indexterm> <indexterm><primary>public routines</primary><secondary>MessageDialog</secondary></indexterm> <programlisting> |
From: <mie...@us...> - 2012-12-06 03:25:05
|
Revision: 8660 http://sourceforge.net/p/oorexx/code-0/8660 Author: miesfeld Date: 2012-12-06 03:24:57 +0000 (Thu, 06 Dec 2012) Log Message: ----------- ooDialog doc - incremental update Modified Paths: -------------- docs/trunk/oodialog/en-US/listview.xml docs/trunk/oodialog/en-US/userInput.xml Modified: docs/trunk/oodialog/en-US/listview.xml =================================================================== --- docs/trunk/oodialog/en-US/listview.xml 2012-12-06 01:05:29 UTC (rev 8659) +++ docs/trunk/oodialog/en-US/listview.xml 2012-12-06 03:24:57 UTC (rev 8660) @@ -9551,10 +9551,51 @@ </para> <para> Normally, the subitems of a list-view item are only thought about when the list-view is in report view. However, once added - to an item, the subitems exist whatever view the list-view is in. A full row object can be used to add or insert items - along with all the subitems of the item, or to query information about an item and its subitems. + to an item, the subitems exist whatever view the list-view is in. A full row object can be used to add or insert list-view + items along with all the subitems of the item, or to query information about a list-view item and its subitems. </para> +<para> + <computeroutput>LvFullRow</computeroutput> objects also provide the infrastructure that allows the ooDialog framework to + <link linkend="mthSortItems">internally</link> sort list-view items. +</para> + +<section id="sctInternalSorting"><title>Internal Sorting Considerations</title> +<indexterm><primary>internal sorting</primary><secondary>LvFullRow Class</secondary></indexterm> +<indexterm><primary>internal sorting</primary><secondary>ListView Class</secondary></indexterm> +<para> + The <xref linkend="mthSortItems"/> method is used to sort list-view items. One option of this method is to have the + ooDialog framework implement the sort internally. The internal sort can be significantly faster, for large lists, than + implementing the sort in Rexx. However, the internal sorting is dependent on the <computeroutput>LvFullRow</computeroutput> + class. There are a few things the Rexx programmer needs to be aware of that effect the ability of the ooDialog framework to + do an internal sort. +</para> +<para> + Any sorting of the list-view items, whether it is through a sort implemented in Rexx or the internal sort, is dependent on + <link linkend="mthSetItemDataClsListView">setting</link> a value for the item data of every list-view item. For the + internal sort to work, the item data value must be a <computeroutput>LvFullRow</computeroutput> object. There are several + approaches that could be used to assign a full row object to the item data of every list-view item. One approach would be + to iterate through all the list-view items, for each item, instantiate a full row object for the item and use the <xref + linkend="mthSetItemDataClsListView"/> method to assign the object to the item. +</para> +<para> + However, full row objects can also be used to add items to the list-view through one the <xref linkend="mthAddFullRow"/>, + <xref linkend="mthInsertFullRow"/>, or <xref linkend="mthPrependFullRow"/> methods. A second approach is to add all + list-view items using full row objects and have the ooDialog framework set the full row object as the item data when the + item is added to the list-view. To use this technique, the programmer should set the <emphasis + role="italic">sorting</emphasis> argument to true when <link linkend="mthNewClsLvFullRow">instantiating</link> the full row + object. +</para> +<para> + In a way, a full row object is a snapshot of the information the list-view control maintains about a specific item in the + list. This information can change over time as the application is used. For instance, the text of an item could be changed. + When a full row object is assigned as the item data of a list-view item, the ooDialog framework does its best to keep the + full row object updated with any changes made to the information of the list-view item. But, there are a few scenarios + where this is not always possibile. The Rexx programmer needs to be aware of these scenarios and take the proper steps to + keep the full row object in synch with the list-view item. +</para> +</section> + <section id="sctMethodsLvFullRow"><title>Method Table</title> <para> The following table lists the class and instance methods of the <computeroutput>LvFullRow</computeroutput> class: @@ -9618,8 +9659,8 @@ <![CDATA[ +--------------+ V | ->>--new(--item--+--------------+--)-------------->< - +--,--subItem--+ +>>--new(--item--+--------------+--+-----------+--)-------------->< + +--,--subItem--+ +-,-sorting-+ ]]> </programlisting> @@ -9645,11 +9686,13 @@ item being added. The argument can repeat has many times as needed to specify all the subitems of the item. The subitems are added to the item in the order of the arguments to the <emphasis role="italic">new</emphasis> method. </para> + </listitem></varlistentry> + <varlistentry><term>sorting [optional]</term> + <listitem> <para> - <emphasis role="bold">Note:</emphasis> The very last argument can optionally be <computeroutput>.true</computeroutput> - or <computeroutput>.false</computeroutput> to signal that the <computeroutput>LvFullRow</computeroutput> object - itself is to be assigned as the item data value of the list-view items. This usage is explained in the remarks - section. + The very last argument can optionally be <computeroutput>.true</computeroutput> or + <computeroutput>.false</computeroutput> to signal that the <computeroutput>LvFullRow</computeroutput> object itself is + to be assigned as the item data value of the list-view items. This usage is explained in the remarks section. </para> </listitem></varlistentry> </variablelist> Modified: docs/trunk/oodialog/en-US/userInput.xml =================================================================== --- docs/trunk/oodialog/en-US/userInput.xml 2012-12-06 01:05:29 UTC (rev 8659) +++ docs/trunk/oodialog/en-US/userInput.xml 2012-12-06 03:24:57 UTC (rev 8660) @@ -913,12 +913,12 @@ </section> <section id="clsSingleSelection" xreflabel="SingleSelection"><title>SingleSelection Class</title> -<indexterm><primary>SingleSelection</primary> -<secondary>class</secondary></indexterm> -<indexterm><primary>standard dialogs</primary> -<secondary>SingleSelection</secondary></indexterm> -<para>The SingleSelection class shows a dialog that has -a group of radio buttons. The user can select only one item of the group. </para> +<indexterm><primary>SingleSelection</primary><secondary>standard dialogs</secondary></indexterm> +<indexterm><primary>standard dialogs</primary><secondary>SingleSelection</secondary></indexterm> +<para> + The <computeroutput>SingleSelection</computeroutput> class presents a dialog that has a group of radio buttons. The user + can select only one item of the group. +</para> <variablelist> <varlistentry><term>Execute:</term> <listitem><para>Returns the number of the radio button selected @@ -926,73 +926,133 @@ </variablelist> <para>The method listed below is defined by this class.</para> -<section id="initSingleSelection" xreflabel="init"><title>init</title> -<indexterm><primary>init</primary> -<secondary>SingleList class</secondary></indexterm> +<section id="mthNewClsSingleSelection" xreflabel="new"><title>new</title> +<indexterm><primary>new</primary><secondary>SingleSelection class</secondary></indexterm> +<indexterm><primary>SingleSelection class</primary><secondary>new</secondary></indexterm> <programlisting> <![CDATA[ ->>-aSingleSelection~init(--message--,--title--,--labels.--,--data--> +>>-new(--msg--,--title--,--labels.--,--+----------+--+---------+--+-------+--)-->< + +-,-preSel-+ +-,-rbLen-+ +-,-max-+ +]]> +</programlisting> +<para> ->--+------------------------+--)------------------------------->< - +-,--+-----+--+--------+-+ - +-len-+ +-,--max-+ +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem><para>The arguments are: + <variablelist> + <varlistentry><term>message</term> + <listitem><para>A text string that is displayed on top of the radio button group. Use + it to give the user advice on what to do. + </para></listitem></varlistentry> + <varlistentry><term>title</term> + <listitem><para>A text string for the title bar + </para></listitem></varlistentry> + <varlistentry><term>labels.</term> + <listitem><para>This argument is a stem variable containing all labels for the radio + buttons + </para></listitem></varlistentry> + <varlistentry><term>data</term> + <listitem><para>You can use this argument to preselect one radio button. A value of + 1 selects the first radio button, a value of 2 selects the second, and so + on. + </para></listitem></varlistentry> + <varlistentry><term>len</term> + <listitem><para>Determines the length of the check boxes and labels. If omitted, the + size is calculated to fit the largest label. + </para></listitem></varlistentry> + <varlistentry><term>max</term> + <listitem><para>The maximum number of radio buttons in one column. If there are more + radio buttons than max - that is, labels. has more items than the value of max + - this method continues with a new column. + </para></listitem></varlistentry> + </variablelist> + </para></listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem><para>The following example creates and executes a dialog that contains a + two-column radio button group. The fifth radio button (the button with the + label May) is preselected. + <programlisting> + <![CDATA[ + mon.1 = "January" ; mon.2 = "February" ; mon.3 = "March" + mon.4 = "April" ; mon.5 = "May" ; mon.6 = "June" + mon.7 = "July" ; mon.8 = "August" ; mon.9 = "September" + mon.10= "October" ; mon.11= "November" ; mon.12= "December" + dlg = .SingleSelection~new("Please select a month!", , + "Single Selection", mon., 5, , 6) + s = dlg~execute + say "You Selected the month: " mon.s + ]]> + </programlisting> + </para></listitem></varlistentry> +</variablelist> +</section> + +<section id="mthExecuteClsSingleSelection" xreflabel="execute"><title>execute</title> +<indexterm><primary>execute</primary><secondary>SingleSelection class</secondary></indexterm> +<indexterm><primary>SingleSelection class</primary><secondary>execute</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--execute(--+--------+--)--------------------------------------------->< + +--type--+ ]]> </programlisting> +<para> + xx +</para> <variablelist> -<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> -<listitem><para>The arguments are: -<variablelist> -<varlistentry><term>message</term> -<listitem><para>A text string that is displayed on top of the radio button group. Use -it to give the user advice on what to do. -</para></listitem></varlistentry> -<varlistentry><term>title</term> -<listitem><para>A text string for the title bar -</para></listitem></varlistentry> -<varlistentry><term>labels.</term> -<listitem><para>This argument is a stem variable containing all labels for the radio -buttons -</para></listitem></varlistentry> -<varlistentry><term>data</term> -<listitem><para>You can use this argument to preselect one radio button. A value of -1 selects the first radio button, a value of 2 selects the second, and so -on. -</para></listitem></varlistentry> -<varlistentry><term>len</term> -<listitem><para>Determines the length of the check boxes and labels. If omitted, the -size is calculated to fit the largest label. -</para></listitem></varlistentry> -<varlistentry><term>max</term> -<listitem><para>The maximum number of radio buttons in one column. If there are more -radio buttons than max - that is, labels. has more items than the value of max -- this method continues with a new column. -</para></listitem></varlistentry> -</variablelist> -</para></listitem></varlistentry> -<varlistentry><term><emphasis role="bold">Example:</emphasis></term> -<listitem><para>The following example creates and executes a dialog that contains a -two-column radio button group. The fifth radio button (the button with the -label May) is preselected. - + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The arguments are: + </para> + <variablelist> + <varlistentry><term>TERM</term> + <listitem> + <para> + xx + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + xx + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + Additional comments. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect usage is detected. + </para> + <para> + Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example ... <programlisting> <![CDATA[ -mon.1 = "January" ; mon.2 = "February" ; mon.3 = "March" -mon.4 = "April" ; mon.5 = "May" ; mon.6 = "June" -mon.7 = "July" ; mon.8 = "August" ; mon.9 = "September" -mon.10= "October" ; mon.11= "November" ; mon.12= "December" -dlg = .SingleSelection~new("Please select a month!", , - "Single Selection", mon., 5, , 6) -s = dlg~execute -say "You Selected the month: " mon.s ]]> </programlisting> -</para></listitem></varlistentry> + </para> + </listitem></varlistentry> </variablelist> -</section> +</section> <!-- End SingleSelection::execute() --> </section> @@ -2180,12 +2240,10 @@ </section> <section id="rtnSingleSelection" xreflabel="SingleSelection"><title>SingleSelection Routine</title> -<indexterm><primary>SingleSelection</primary> -<secondary>function</secondary></indexterm> -<indexterm><primary>public routines</primary> -<secondary>SingleSelection</secondary></indexterm> +<indexterm><primary>SingleSelection</primary><secondary>function</secondary></indexterm> +<indexterm><primary>public routines</primary><secondary>SingleSelection</secondary></indexterm> <para> - The SingleSelection function provides a shortcut means to invoke a<xref linkend="clsSingleSelection"/> dialog + The SingleSelection function provides a shortcut means to invoke a <xref linkend="clsSingleSelection"/> dialog </para> <programlisting> <![CDATA[ @@ -2207,7 +2265,7 @@ ]]> </programlisting> <para> - The parameters are described in the <xref linkend="initSingleSelection"/>) method of the + The parameters are described in the <xref linkend="mthNewClsSingleSelection"/>) method of the <computeroutput>SingleSelection</computeroutput> class. However, instead of an input stem an array is passed into the function. </para> |
From: <mie...@us...> - 2012-12-07 00:41:20
|
Revision: 8664 http://sourceforge.net/p/oorexx/code-0/8664 Author: miesfeld Date: 2012-12-07 00:41:16 +0000 (Fri, 07 Dec 2012) Log Message: ----------- ooDialog doc - incremental update Modified Paths: -------------- docs/trunk/oodialog/en-US/dialogObject.xml docs/trunk/oodialog/en-US/listview.xml docs/trunk/oodialog/en-US/userInput.xml docs/trunk/oodialog/en-US/utilityclasses.xml Modified: docs/trunk/oodialog/en-US/dialogObject.xml =================================================================== --- docs/trunk/oodialog/en-US/dialogObject.xml 2012-12-07 00:01:57 UTC (rev 8663) +++ docs/trunk/oodialog/en-US/dialogObject.xml 2012-12-07 00:41:16 UTC (rev 8664) @@ -807,6 +807,10 @@ <entry>Calculates the size needed for a string in pixels.</entry> </row> <row> +<entry><xref linkend="mthGetTextSizeTitleBar"/></entry> +<entry>Gets the size, width and height, of a string used in the caption bar for the title.</entry> +</row> +<row> <entry><xref linkend="deGetWindowDC"/></entry> <entry>Returns the device context of a window.</entry> </row> @@ -9276,7 +9280,73 @@ </variablelist> </section> <!-- End PlainBaseDialog::getTextSizeDlg() --> +<section id="mthGetTextSizeTitleBar" xreflabel="getTextSizeTitleBar"><title>getTextSizeTitleBar</title> +<indexterm><primary>getTextSizeTitleBar</primary></indexterm> +<indexterm><primary>dialog object</primary><secondary>getTextSizeTitleBar</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--getTextSizeTitleBar(--text--)---------------->< +]]> +</programlisting> +<para> + Gets the size, width and height, of a string used in the caption bar for the title. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The single argument is: + </para> + <variablelist> + <varlistentry><term>text [required]</term> + <listitem> + <para> + The string to get the size of. This can be any string, it does not have to be the actual string used for the title. + This method returns the size for the string, if it were to be used in the caption bar. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + Returns a <xref linkend="clsSize"/> object containing the width and height of a rectangle that would contain the string. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + This method can be used before the underlying Windows dialog is created. The returned size is identical whether the + dialog has been created by the operating system or not. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example calculates the width, in dialog units, that is required for a dialog such that the title fits without the + operating system clipping it: +<programlisting> +<![CDATA[ + +::method getMinDlgCX private + use strict arg title + + s = self~getTextSizeTitleBar(title) + + padding = 18 + s~width += (2 * .SM~cxFixedFrame) + .SM~cxSize + .SM~cxSmIcon + padding + self~pixel2dlgUnit(s) + + return s~width +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End PlainBaseDialog::getTextSizeTitleBar() --> + + <section id="mthPixel2dlgUnit" xreflabel="pixel2dlgUnit"><title>pixel2dlgUnit</title> <indexterm><primary>pixel2dlgUnit</primary></indexterm> <indexterm><primary>dialog object</primary><secondary>pixel2dlgUnit</secondary></indexterm> Modified: docs/trunk/oodialog/en-US/listview.xml =================================================================== --- docs/trunk/oodialog/en-US/listview.xml 2012-12-07 00:01:57 UTC (rev 8663) +++ docs/trunk/oodialog/en-US/listview.xml 2012-12-07 00:41:16 UTC (rev 8664) @@ -124,8 +124,8 @@ <table id="tblListViewMethods" frame="all"> <title>ListView Instance Methods</title> <tgroup cols="2"> -<colspec colwidth="2*" /> <colspec colwidth="7*" /> +<colspec colwidth="21*" /> <thead> <row> <entry>Method</entry> @@ -1063,7 +1063,7 @@ </variablelist> </section> -<section id="mthAddFullRow"><title>addFullRow</title> +<section id="mthAddFullRow" xreflabel="addFullRow"><title>addFullRow</title> <indexterm><primary>addFullRow</primary></indexterm> <indexterm><primary>ListView class</primary><secondary>addFullRow</secondary></indexterm> <programlisting> @@ -1080,6 +1080,7 @@ <listitem> <para> The single argument is: + </para> <variablelist> <varlistentry><term>row [required]</term> <listitem> @@ -1088,7 +1089,6 @@ </para> </listitem></varlistentry> </variablelist> - </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> @@ -4238,7 +4238,7 @@ </section> <!-- End ListView::insertColumnPX() --> -<section id="mthInsertFullRow"><title>insertFullRow</title> +<section id="mthInsertFullRow" xreflabel="getFullRow"><title>insertFullRow</title> <indexterm><primary>insertFullRow</primary></indexterm> <indexterm><primary>ListView class</primary><secondary>insertFullRow</secondary></indexterm> <programlisting> @@ -5174,7 +5174,7 @@ </variablelist> </section> -<section id="mthPrependFullRow"><title>prependFullRow</title> +<section id="mthPrependFullRow" xreflabel="prependFullRow"><title>prependFullRow</title> <indexterm><primary>prependFullRow</primary></indexterm> <indexterm><primary>ListView class</primary><secondary>prependFullRow</secondary></indexterm> <programlisting> @@ -9560,42 +9560,6 @@ </para> -<section id="sctInternalSorting"><title>Internal Sorting Considerations</title> -<indexterm><primary>internal sorting</primary><secondary>LvFullRow Class</secondary></indexterm> -<indexterm><primary>internal sorting</primary><secondary>ListView Class</secondary></indexterm> -<para> - The <xref linkend="mthSortItems"/> method is used to sort list-view items. One option of this method is to have the - ooDialog framework implement the sort internally. The internal sort can be significantly faster, for large lists, than - implementing the sort in Rexx. However, the internal sorting is dependent on the <computeroutput>LvFullRow</computeroutput> - class. There are a few things the Rexx programmer needs to be aware of that effect the ability of the ooDialog framework to - do an internal sort. -</para> -<para> - Any sorting of the list-view items, whether it is through a sort implemented in Rexx or the internal sort, is dependent on - <link linkend="mthSetItemDataClsListView">setting</link> a value for the item data of every list-view item. For the - internal sort to work, the item data value must be a <computeroutput>LvFullRow</computeroutput> object. There are several - approaches that could be used to assign a full row object to the item data of every list-view item. One approach would be - to iterate through all the list-view items, for each item, instantiate a full row object for the item and use the <xref - linkend="mthSetItemDataClsListView"/> method to assign the object to the item. -</para> -<para> - However, full row objects can also be used to add items to the list-view through one the <xref linkend="mthAddFullRow"/>, - <xref linkend="mthInsertFullRow"/>, or <xref linkend="mthPrependFullRow"/> methods. A second approach is to add all - list-view items using full row objects and have the ooDialog framework set the full row object as the item data when the - item is added to the list-view. To use this technique, the programmer should set the <emphasis - role="italic">sorting</emphasis> argument to true when <link linkend="mthNewClsLvFullRow">instantiating</link> the full row - object. -</para> -<para> - In a way, a full row object is a snapshot of the information the list-view control maintains about a specific item in the - list. This information can change over time as the application is used. For instance, the text of an item could be changed. - When a full row object is assigned as the item data of a list-view item, the ooDialog framework does its best to keep the - full row object updated with any changes made to the information of the list-view item. But, there are a few scenarios - where this is not always possibile. The Rexx programmer needs to be aware of these scenarios and take the proper steps to - keep the full row object in synch with the list-view item. -</para> -</section> - <section id="sctMethodsLvFullRow"><title>Method Table</title> <para> The following table lists the class and instance methods of the <computeroutput>LvFullRow</computeroutput> class: @@ -9652,6 +9616,95 @@ </para> </section> +<section id="sctInternalSorting"><title>Internal Sorting Considerations</title> +<indexterm><primary>internal sorting</primary><secondary>LvFullRow Class</secondary></indexterm> +<indexterm><primary>internal sorting</primary><secondary>ListView Class</secondary></indexterm> +<para> + The <xref linkend="mthSortItems"/> method is used to sort list-view items. One option of this method is to have the + ooDialog framework implement the sort internally. The internal sort can be significantly faster, for large lists, than + implementing the sort in Rexx. However, the internal sorting is dependent on the <computeroutput>LvFullRow</computeroutput> + class. There are a few things the Rexx programmer needs to be aware of that effect the ability of the ooDialog framework to + do an internal sort. +</para> +<para> + Any sorting of the list-view items, whether it is through a sort implemented in Rexx or the internal sort, is dependent on + <link linkend="mthSetItemDataClsListView">setting</link> a value for the item data of every list-view item. For the + internal sort to work, the item data value must be a <computeroutput>LvFullRow</computeroutput> object. There are several + approaches that could be used to assign a full row object to the item data of every list-view item. One approach would be + to iterate through all the list-view items, for each item, instantiate a full row object for the item and use the <xref + linkend="mthSetItemDataClsListView"/> method to assign the object to the item. +</para> +<para> + However, full row objects can also be used to add items to the list-view through one the <xref linkend="mthAddFullRow"/>, + <xref linkend="mthInsertFullRow"/>, or <xref linkend="mthPrependFullRow"/> methods. A second approach is to add all + list-view items using full row objects and have the ooDialog framework set the full row object as the item data when the + item is added to the list-view. To use this technique, the programmer should set the <emphasis + role="italic">sorting</emphasis> argument to true when <link linkend="mthNewClsLvFullRow">instantiating</link> the full row + object. +</para> +<para> + In a way, a full row object is a snapshot of the information the list-view control maintains about a specific item in the + list. This information can change over time as the application is used. For instance, the text of an item could be changed. + When a full row object is assigned as the item data of a list-view item, the ooDialog framework does its best to keep the + full row object updated with any changes made to the information of the list-view item. But, there is one scenario where + this is not always possibile. The Rexx programmer needs to be aware of this and take the proper steps to keep the full row + object in synch with the list-view item. +</para> +<para> + When a column in the list-view is <link linkend="mthInsertColumnPX">inserted</link> + or <link linkend="mthDeleteColumn">deleted</link>, the list-view control adds or deletes the subitems of all + items that corresponds to the colum. Every item in a list-view always has the same number of subitems. If all items in the + list-view have a <computeroutput>LvFullRow</computeroutput> object set as the item data, when a column is deleted, the full + row object will have one too many subitems. The same if a column is added, the full row object will have no knowledge of + the new subitem. <emphasis role="bold">Note</emphasis> that there is no problem the very first time a column is inserted + in a list-view. In addition, this discussion only concerns the case where <computeroutput>LvFullRow</computeroutput> + objects have been assigned to the item data of each item to faciliate internal sorting. +</para> +<para> + Most ooDialog programs that use a list-view do not involve inserting or removing columns after the list-view items have + been added. But, for programs that do <emphasis role="italic">and</emphasis> use <computeroutput>LvFullRow</computeroutput> + objects to allow internal sorting, the programmer must take an additional step when a column is inserted or deleted. This + ensures the integrity of the full row objects. ooDialog provides 3 methods to ensure integrity when a column is inserted or + deleted: +</para> + +<variablelist> + <varlistentry><term><emphasis role="bold">The fixFullRowColumns method:</emphasis></term> + <listitem> + <para> + ooDialog provides the <xref linkend="mthFixFullRowColumns"/> method, !xr + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">The adjustFullRows argument:</emphasis></term> + <listitem> + <para> + xxx and xxx sss. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Manual update</emphasis></term> + <listitem> + <para> + With this method, after the column insert or delete, the programmer iterates through all the list-view items, removes the + old invalid item data, creates a valid full row object, and sets the item data to the new full row object. The following + code snippet shows the procedure: + </para> + </listitem></varlistentry> +<programlisting> +<![CDATA[ + + list~deleteColumn(delCol) + + do i = 0 to list~items + list~removeItemData(i) + lvFullRow = list~getFullRow(i, .true) + list~setItemData(i, lvFullRow) + end + +]]> +</programlisting> +</variablelist> +</section> + <section id="mthNewClsLvFullRow" xreflabel="new"><title>new (Class Method)</title> <indexterm><primary>new</primary><secondary>LvFullRow class</secondary></indexterm> <indexterm><primary>LvFullRow class</primary><secondary>new</secondary></indexterm> Modified: docs/trunk/oodialog/en-US/userInput.xml =================================================================== --- docs/trunk/oodialog/en-US/userInput.xml 2012-12-07 00:01:57 UTC (rev 8663) +++ docs/trunk/oodialog/en-US/userInput.xml 2012-12-07 00:41:16 UTC (rev 8664) @@ -99,7 +99,7 @@ <para> The ooDialog framework provides a number of easy to use dialogs and routines that obtain user input in common scenarios. These dialogs and routines allow programmers to include simple graphical elements in their Rexx - applications and collect user input in a standard way.. The public routines can be called with a single line of code + applications and collect user input in a standard way. The public routines can be called with a single line of code and the standard dialogs can usually be executed with only two lines of code. This does not require the programmer to do much set up and makes them simple to work with. </para> @@ -112,8 +112,8 @@ <table id="tStandardElements" frame="all"> <title>Common Dialog Classes and Public Routines</title> <tgroup cols="2"> -<colspec colwidth="1*" /> -<colspec colwidth="4*" /> +<colspec colwidth="11*" /> +<colspec colwidth="32*" /> <thead> <row> <entry>Class / Routine</entry> @@ -349,178 +349,6 @@ </section> </section> -<section id="clsTimedMessage" xreflabel="TimedMessage"><title>TimedMessage Class</title> -<indexterm><primary>TimedMessage</primary> -<secondary>class</secondary></indexterm> -<indexterm><primary>standard dialogs</primary> -<secondary>TimedMessage</secondary></indexterm> -<para>The TimeMessage class shows a message window for -a defined duration. </para> -<para>The methods listed below are defined by this class.</para> - -<section id="initTimedMessage" xreflabel="init"><title>init</title> -<indexterm><primary>init</primary> -<secondary>TimedMessage class</secondary></indexterm> -<programlisting> -<![CDATA[ ->>-aTimedMessage~init(--msg-,-title-,-sleeping--+--------------+-+-----+--)---->< - +-,-earlyReply-+ +-,-p-+ - -]]> -</programlisting> - -<para>The init method prepares the dialog. </para> -<variablelist> -<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> -<listitem><para>The arguments are: -<variablelist> -<varlistentry><term>message</term> -<listitem><para>A string that is displayed inside the window as a message. The length -of the message determines the horizontal size of all standard dialogs. -</para></listitem></varlistentry> -<varlistentry><term>title</term> -<listitem><para>A string that is displayed as the window title in the title bar of the -dialog -</para></listitem></varlistentry> -<varlistentry><term>sleeping</term> -<listitem><para>A number that determines how long (in milliseconds) the window -is shown. If this number is 0 or greater, the message window is shown for that -time and automatically dismisses itself. The programmer need take no further -action. -</para> -<para>If the number is less than 0 then the message window is shown -indefinitely. The <computeroutput>execute</computeroutput> method returns -immediately. In this case, the programmer needs to dismiss the window manually. -This is done by invoking the <computeroutput>ok</computeroutput> method. See -<emphasis role="bold">Example 2</emphasis> below. -</para></listitem></varlistentry> -<varlistentry><term>earlyReply</term> -<listitem><para>The optional early reply argument defaults to false. If used -and if true, the <computeroutput>execute</computeroutput> method of the dialog -returns immediately. This allows the code at the point where <computeroutput> -execute</computeroutput> was invoked to continue. The message windows continues -to display for its specified duration and then dismisses itself automatically. -</para></listitem></varlistentry> -<varlistentry><term>p [optional]</term> -<listitem> -<para> - A <xref linkend="clsPoint"/> object that specifies the position, in pixels, for the position of the timed - message dialog on the screen. By default the dialog is centered in the screen. If <emphasis role="italic">p</emphasis> - is used, the point specifies the position of the upper left corner of the dialog. -</para> -</listitem></varlistentry> -</variablelist> -</para></listitem></varlistentry> -<varlistentry id="example1TimedMessage"><term><emphasis role="bold">Example - 1:</emphasis></term> -<listitem><para>The following example shows a window with the title of <emphasis -role="italic">Infomation</emphasis> for a duration of 3 seconds: -<programlisting> -<![CDATA[ -dlg = .TimedMessage~New("Application will be started, please wait", - - "Information", 3000) -dlg~execute -drop dlg -]]> -</programlisting> -</para></listitem></varlistentry> -<varlistentry id="example2TimedMessage"><term><emphasis role="bold">Example -2:</emphasis></term> -<listitem><para>The following example shows an introductory window that displays -while an application is doing its time consuming start up routine. Since this -start up process can vary in time depending on the individual system, the window -is set to display indefinitely. When the start up process is finished, the -programmer dismisses the window and destroys the dialog manually. -<programlisting> -<![CDATA[ -dlg = .TimedMessage~New("The WidgetCreator Application - loading ...", - - "The Widget Factory", -1) -dlg~execute -ret = doStartup() -dlg~ok -drop dlg -if ret <> 0 then do - ... -end -]]> -</programlisting> -</para></listitem></varlistentry> -<varlistentry id="example3TimedMessage"><term><emphasis role="bold">Example -3:</emphasis></term> -<listitem><para>The following example is a variation on <emphasis role="bold"> -Example 2</emphasis>. In this case the Widget Factory executives decided that -they want their WidgeCreator splash screen to always display for 2 seconds to -the customer and then close. The early reply argument is used so that the start -up routine executes immediately. After 2 seconds the splash screen dismisses -and the dialog is destroyed automatically. -</para> -<note><title>Note</title><para>It is not necessary to explicitly drop the dlg -variable. That is shown in the other examples to emphasize the point that the -dialog has been destroyed.</para></note> -<programlisting> <![CDATA[ -dlg = .TimedMessage~New("The WidgetCreator Application - loading ...", - - "The Widget Factory", 2000) -dlg~execute -if doStartup() <> 0 then do - ... -end -]]> -</programlisting></listitem></varlistentry> -</variablelist> -</section> - -<section id="defDlgTimedMessage"><title>defineDialog</title> -<indexterm><primary>Define</primary> -<secondary>TimedMessage</secondary></indexterm> -<programlisting> -<![CDATA[ ->>-aTimedMessage~DefineDialog---------------------------------->< - -]]> -</programlisting> - -<para>The defineDialog method is called by the create method of the parent -class, PlainUserDialog, which in turn is called at the very beginning of -Execute. You do not have to call it. However, you may want to over-ride it in -your subclass to add more dialog controls to the window. If you over-ride it, -you have to forward the message to the parent class by using the keyword super. -</para> -<variablelist> -<varlistentry><term><emphasis role="bold">Example:</emphasis></term> -<listitem><para>The following example shows how to subclass the TimedMessage -class and how to add a background bitmap to the dialog window: -<programlisting> -<![CDATA[ -::class MyTimedMessage subclass TimedMessage inherit DialogExtensions - -::method defineDialog - self~backgroundBitmap("mybackg.bmp", "USEPAL") - self~DefineDialog:super() -]]> -</programlisting> -</para></listitem></varlistentry> -</variablelist> -</section> - -<section id="h002097"><title>execute</title> -<indexterm><primary>execute</primary> -<secondary>TimedMessage class</secondary></indexterm> -<programlisting> -<![CDATA[ ->>-aTimedMessage~Execute--------------------------------------->< -]]> -</programlisting> - -<para> - The execute method creates and shows the message window. If the specified <link linkend="initTimedMessage">duration</link> - is not negative, this method destroys the dialog automatically when the duration is up. If the duration is less than 0, - then the programmer must destroy the dialog manually by invoking the <computeroutput>ok</computeroutput> method. See this - <link linkend="example2TimedMessage">example</link> for a code snippet showing the procedure. -</para> -</section> - -</section> - <section id="clsInputBox" xreflabel="InputBox"><title>InputBox Class</title> <indexterm><primary>InputBox</primary> <secondary>class</secondary></indexterm> @@ -671,37 +499,76 @@ </section> </section> -<section id="clsPasswordBox" xreflabel="PasswordBox"><title>PasswordBox Class</title> -<indexterm><primary>PasswordBox</primary> +<section id="clsListChoice" xreflabel="ListChoice"><title>ListChoice Class</title> +<indexterm><primary>ListChoice</primary> <secondary>class</secondary></indexterm> <indexterm><primary>standard dialogs</primary> -<secondary>PasswordBox</secondary></indexterm> -<para>The PasswordBox class is an InputBox dialog with an entry line that echoes the keys with asterisks -(*) instead of characters. </para> +<secondary>ListChoice</secondary></indexterm> +<para>The ListChoice class provides a dialog with a list +box, an OK, and a Cancel button. +The selected item is returned if the OK push button +is used to terminate the dialog. </para> <variablelist> -<varlistentry><term>Subclass:</term> -<listitem><para>This class is a subclass of the InputBox <xref linkend="clsInputBox"/> -</para></listitem></varlistentry> <varlistentry><term>Execute:</term> -<listitem><para>Returns the user's password +<listitem><para>Returns the user's choice or a null string </para></listitem></varlistentry> </variablelist> -<para>The methods are the same as for the InputBox <xref linkend="clsInputBox"/>, -with the exception of AddLine.</para> +<para>The method listed below is defined by this class.</para> -<section id="h002166"><title>AddLine</title> -<indexterm><primary>AddLine</primary> -<secondary>PasswordBox class</secondary></indexterm> +<section id="initListChoice" xreflabel="init"><title>init</title> +<indexterm><primary>init</primary> +<secondary>ListChoice class</secondary></indexterm> <programlisting> <![CDATA[ ->>-aPasswordBox~AddLine(--x--,--y--,--l--)--------------------->< +>>-aListChoice~init(--message--,--title--,--input.--------------> +>--+---------------------------------------------------+------->< + +-,--+------+--+-------------------------------+--)-+ + +-lenx-+ +-,--+------+--+--------------+-+ + +-leny-+ +-,--preselect-+ + + ]]> </programlisting> -<para>The AddLine overrides the same method of the parent -class, InputBox, by using a password entry line instead -of a simple entry line.</para> +<para>The init method is used to initialize a newly created +instance of this class. </para> +<variablelist> +<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> +<listitem><para>The arguments are: +<variablelist> +<varlistentry><term>message</term> +<listitem><para>A text string that is displayed on top of the list box. Use it to give +the user advice on what to do. +</para></listitem></varlistentry> +<varlistentry><term>title</term> +<listitem><para>A text string for the dialog's title +</para></listitem></varlistentry> +<varlistentry><term>input.</term> +<listitem><para>A stem variable (do not forget the trailing period) containing string +values that are inserted into the list box +</para></listitem></varlistentry> +<varlistentry><term>lenx, leny</term> +<listitem><para>The size of the list box in dialog units +</para></listitem></varlistentry> +<varlistentry><term>preselect</term> +<listitem><para>Entry that is selected when list pops up +</para></listitem></varlistentry> +</variablelist> +</para></listitem></varlistentry> +<varlistentry><term><emphasis role="bold">Example:</emphasis></term> +<listitem><para>The following example creates a list choice dialog box where the user +can select exactly one dessert: +</para></listitem></varlistentry> +</variablelist> +<programlisting> +<![CDATA[ +lst.1 = "Cookies"; lst.2 = "Pie"; lst.3 = "Ice cream"; lst.4 = "Fruit" + +dlg = .ListChoice~new("Select the dessert please","YourChoice",lst., , ,"Pie") +say "Your ListChoice data:" dlg~execute +]]> +</programlisting> </section> </section> @@ -792,79 +659,6 @@ </section> </section> -<section id="clsListChoice" xreflabel="ListChoice"><title>ListChoice Class</title> -<indexterm><primary>ListChoice</primary> -<secondary>class</secondary></indexterm> -<indexterm><primary>standard dialogs</primary> -<secondary>ListChoice</secondary></indexterm> -<para>The ListChoice class provides a dialog with a list -box, an OK, and a Cancel button. -The selected item is returned if the OK push button -is used to terminate the dialog. </para> -<variablelist> -<varlistentry><term>Execute:</term> -<listitem><para>Returns the user's choice or a null string -</para></listitem></varlistentry> -</variablelist> -<para>The method listed below is defined by this class.</para> - -<section id="initListChoice" xreflabel="init"><title>init</title> -<indexterm><primary>init</primary> -<secondary>ListChoice class</secondary></indexterm> -<programlisting> -<![CDATA[ ->>-aListChoice~init(--message--,--title--,--input.--------------> - ->--+---------------------------------------------------+------->< - +-,--+------+--+-------------------------------+--)-+ - +-lenx-+ +-,--+------+--+--------------+-+ - +-leny-+ +-,--preselect-+ - - -]]> -</programlisting> - -<para>The init method is used to initialize a newly created -instance of this class. </para> -<variablelist> -<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> -<listitem><para>The arguments are: -<variablelist> -<varlistentry><term>message</term> -<listitem><para>A text string that is displayed on top of the list box. Use it to give -the user advice on what to do. -</para></listitem></varlistentry> -<varlistentry><term>title</term> -<listitem><para>A text string for the dialog's title -</para></listitem></varlistentry> -<varlistentry><term>input.</term> -<listitem><para>A stem variable (do not forget the trailing period) containing string -values that are inserted into the list box -</para></listitem></varlistentry> -<varlistentry><term>lenx, leny</term> -<listitem><para>The size of the list box in dialog units -</para></listitem></varlistentry> -<varlistentry><term>preselect</term> -<listitem><para>Entry that is selected when list pops up -</para></listitem></varlistentry> -</variablelist> -</para></listitem></varlistentry> -<varlistentry><term><emphasis role="bold">Example:</emphasis></term> -<listitem><para>The following example creates a list choice dialog box where the user -can select exactly one dessert: -</para></listitem></varlistentry> -</variablelist> -<programlisting> -<![CDATA[ -lst.1 = "Cookies"; lst.2 = "Pie"; lst.3 = "Ice cream"; lst.4 = "Fruit" - -dlg = .ListChoice~new("Select the dessert please","YourChoice",lst., , ,"Pie") -say "Your ListChoice data:" dlg~execute -]]> -</programlisting> -</section> -</section> - <section id="clsMultiListChoice" xreflabel="MultiListChoice"><title>MultiListChoice Class</title> <indexterm><primary>MultiListChoice</primary> <secondary>class</secondary></indexterm> @@ -912,82 +706,144 @@ </programlisting> </section> -<section id="clsSingleSelection" xreflabel="SingleSelection"><title>SingleSelection Class</title> -<indexterm><primary>SingleSelection</primary><secondary>standard dialogs</secondary></indexterm> -<indexterm><primary>standard dialogs</primary><secondary>SingleSelection</secondary></indexterm> -<para> - The <computeroutput>SingleSelection</computeroutput> class presents a dialog that has a group of radio buttons. The user - can select only one item of the group. -</para> +<section id="clsPasswordBox" xreflabel="PasswordBox"><title>PasswordBox Class</title> +<indexterm><primary>PasswordBox</primary> +<secondary>class</secondary></indexterm> +<indexterm><primary>standard dialogs</primary> +<secondary>PasswordBox</secondary></indexterm> +<para>The PasswordBox class is an InputBox dialog with an entry line that echoes the keys with asterisks +(*) instead of characters. </para> <variablelist> +<varlistentry><term>Subclass:</term> +<listitem><para>This class is a subclass of the InputBox <xref linkend="clsInputBox"/> +</para></listitem></varlistentry> <varlistentry><term>Execute:</term> -<listitem><para>Returns the number of the radio button selected +<listitem><para>Returns the user's password </para></listitem></varlistentry> </variablelist> -<para>The method listed below is defined by this class.</para> +<para>The methods are the same as for the InputBox <xref linkend="clsInputBox"/>, +with the exception of AddLine.</para> +<section id="h002166"><title>AddLine</title> +<indexterm><primary>AddLine</primary> +<secondary>PasswordBox class</secondary></indexterm> +<programlisting> +<![CDATA[ +>>-aPasswordBox~AddLine(--x--,--y--,--l--)--------------------->< + +]]> +</programlisting> + +<para>The AddLine overrides the same method of the parent +class, InputBox, by using a password entry line instead +of a simple entry line.</para> +</section> +</section> + +<section id="clsSingleSelection" xreflabel="SingleSelection"><title>SingleSelection Class</title> +<indexterm><primary>SingleSelection</primary><secondary>standard dialog</secondary></indexterm> +<indexterm><primary>standard dialogs</primary><secondary>SingleSelection</secondary></indexterm> +<para> + The <computeroutput>SingleSelection</computeroutput> class presents a dialog that has a group of <link + linkend="clsRadioButton">radio</link> buttons. The user can select only one item of the group, or cancel the dialog. The + programmer can specify how many radio buttons are in the group, if they should be placed in one, or several, columns. The + ooDialog framework internally handles all the layout of the controls of the dialog. This makes the dialog class very easy + to use. +</para> +<para> + The basic steps to user the <computeroutput>SingleSelection</computeroutput> are to instantiate the dialog using the + <emphasis role="italic">new</emphasis> method, run the dialog using the <emphasis role="italic">execute</emphasis> method, + and do something with the user's repsonse which is returned from the <emphasis role="italic">execute</emphasis> method. +</para> + <section id="mthNewClsSingleSelection" xreflabel="new"><title>new</title> <indexterm><primary>new</primary><secondary>SingleSelection class</secondary></indexterm> <indexterm><primary>SingleSelection class</primary><secondary>new</secondary></indexterm> <programlisting> <![CDATA[ ->>-new(--msg--,--title--,--labels.--,--+----------+--+---------+--+-------+--)-->< - +-,-preSel-+ +-,-rbLen-+ +-,-max-+ +>>-new(--msg--,--title--,--labels.--,--+----------+--+-----------+--+-------+--)-->< + +-,-preSel-+ +-,-rbWidth-+ +-,-max-+ ]]> </programlisting> <para> - + Instantiates a new <computeroutput>SingleSelection</computeroutput> object. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> - <listitem><para>The arguments are: + <listitem> + <para> + The arguments are: + </para> <variablelist> - <varlistentry><term>message</term> - <listitem><para>A text string that is displayed on top of the radio button group. Use - it to give the user advice on what to do. - </para></listitem></varlistentry> - <varlistentry><term>title</term> - <listitem><para>A text string for the title bar - </para></listitem></varlistentry> - <varlistentry><term>labels.</term> - <listitem><para>This argument is a stem variable containing all labels for the radio - buttons - </para></listitem></varlistentry> - <varlistentry><term>data</term> - <listitem><para>You can use this argument to preselect one radio button. A value of - 1 selects the first radio button, a value of 2 selects the second, and so - on. - </para></listitem></varlistentry> - <varlistentry><term>len</term> - <listitem><para>Determines the length of the check boxes and labels. If omitted, the - size is calculated to fit the largest label. - </para></listitem></varlistentry> - <varlistentry><term>max</term> - <listitem><para>The maximum number of radio buttons in one column. If there are more - radio buttons than max - that is, labels. has more items than the value of max - - this method continues with a new column. - </para></listitem></varlistentry> + <varlistentry><term>msg [required]</term> + <listitem> + <para> + A text string that is displayed above the radio button group. Typically, the text would be used to give the user the + purpose of the radio buttons. + </para> + </listitem></varlistentry> + <varlistentry><term>title [required]</term> + <listitem> + <para> + A title, the caption bar text, for the dialog + </para> + </listitem></varlistentry> + <varlistentry><term>labels. [reuired]</term> + <listitem> + <para> + A stem with whole number numeric indexes, one through the number of radio buttons desired. The value for each index is + the label for the corresponding radio button. For instance <computeroutput>labels.2</computeroutput> would be set to + the label for the second radio button. + </para> + </listitem></varlistentry> + <varlistentry><term>preSel [optional]</term> + <listitem> + <para> + This argument can be used to preselect, (check,) one radio button. A value of 1 checks the first radio button, a + value of 2 checks the second, and so on. If this argument is omitted, the first radio button is checked. + </para> + </listitem></varlistentry> + <varlistentry><term>rbWidth [optiona]</term> + <listitem> + <para> + Specifies the width, in dialog units, of the radio button controls. If omitted, the width is calculated so that the + longest label will not be clipped. If used, all radio buttons are set to this width without regard as to whether the + label will be clipped or not. + </para> + </listitem></varlistentry> + <varlistentry><term>max [optional]</term> + <listitem> + <para> + The maximum number of radio buttons in one column. If there are more radio buttons than <emphasis + role="italic">max</emphasis>, that is, if the <emphasis role="italic">labels.</emphasis> argument has more indexes + than the value of <emphasis role="italic">max</emphasis>, the radio buttons are positioned in columns. Each column will + have <emphasis role="italic">max</emphasis> radio buttons and ther will be as many columns as needed to display all the + radio buttons. + </para> + </listitem></varlistentry> </variablelist> - </para></listitem></varlistentry> + </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> - <listitem><para>The following example creates and executes a dialog that contains a - two-column radio button group. The fifth radio button (the button with the - label May) is preselected. + <listitem> + <para> + The following example instantiates and executes a dialog that contains a two-column radio button group. The fifth radio + button (the button with the label May) is preselected. - <programlisting> - <![CDATA[ - mon.1 = "January" ; mon.2 = "February" ; mon.3 = "March" - mon.4 = "April" ; mon.5 = "May" ; mon.6 = "June" - mon.7 = "July" ; mon.8 = "August" ; mon.9 = "September" - mon.10= "October" ; mon.11= "November" ; mon.12= "December" +<programlisting> +<![CDATA[ +mon.1 = "January" ; mon.2 = "February" ; mon.3 = "March" +mon.4 = "April" ; mon.5 = "May" ; mon.6 = "June" +mon.7 = "July" ; mon.8 = "August" ; mon.9 = "September" +mon.10= "October" ; mon.11= "November" ; mon.12= "December" - dlg = .SingleSelection~new("Please select a month!", , - "Single Selection", mon., 5, , 6) - s = dlg~execute - say "You Selected the month: " mon.s - ]]> - </programlisting> - </para></listitem></varlistentry> +dlg = .SingleSelection~new("Please select a month:", , + "Single Selection", mon., 5, , 6) +s = dlg~execute +say "You Selected the month:" mon.s +]]> +</programlisting> + </para> + </listitem></varlistentry> </variablelist> </section> @@ -996,57 +852,64 @@ <indexterm><primary>SingleSelection class</primary><secondary>execute</secondary></indexterm> <programlisting> <![CDATA[ ->>--execute(--+--------+--)--------------------------------------------->< - +--type--+ +>>--execute-------------------------------------->< ]]> </programlisting> <para> - xx + Executes the dialog and returns the user's selection or the empty string if the user cancels the dialog. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The arguments are: + There are no arguments to this method </para> - <variablelist> - <varlistentry><term>TERM</term> - <listitem> - <para> - xx - </para> - </listitem></varlistentry> - </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + If the user cancels the dialog, the empty string is returned. If the user closes the dialog with <emphasis + role="italic">Ok</emphasis> the return is the number of the selected radio button. 1 for the first radio button, 2 for + the second radio button, 8 for the eighth radion button, etc., etc.. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + When the <emphasis role="italic">execute</emphasis> method is invoked, the ooDialog framework, internally, does a number + of calculations to determine the optimal size of the dialog controls and dialog. The framework then positions all the + dialog controls such that none of the radio button labels, message, and title of the dialog are clipped. </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details</emphasis></term> - <listitem> <para> - Raises syntax errors when incorrect usage is detected. + The one exception to this is if the programmer specifies the width of the radio button controls using the optional + <emphasis role="italic">rbWidth</emphasis> argument in the <xref linkend="mthNewClsSingleSelection"/> method. In that + case the width of the radio buttons is always set to what the programmer has specified. It is possible that the radio + buttons will be clipped, but that is now the responsibility of the programmer. </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example instantiates a single selection dialog <programlisting> <![CDATA[ +rex.1 = "Regina" ; rex.2 = "ooRexx" ; rex.3 = "Reginald" ; rex.4 = "Personal Rexx" + +d = .SingleSelection~new("Pick your favorite Rexx", "Rexx is King", rex., 2, , 2) +index = d~execute + +if index == "" then say "You failed to pick a Rexx interpreter." +else say "The Rexx you picked:" rex.index + +::requires 'ooDialog.cls' + +/* Output will most likely be: + +The Rexx you picked: ooRexx + +*/ ]]> </programlisting> </para> @@ -1056,9 +919,181 @@ </section> +<section id="clsTimedMessage" xreflabel="TimedMessage"><title>TimedMessage Class</title> +<indexterm><primary>TimedMessage</primary> +<secondary>class</secondary></indexterm> +<indexterm><primary>standard dialogs</primary> +<secondary>TimedMessage</secondary></indexterm> +<para>The TimeMessage class shows a message window for +a defined duration. </para> +<para>The methods listed below are defined by this class.</para> + +<section id="initTimedMessage" xreflabel="init"><title>init</title> +<indexterm><primary>init</primary> +<secondary>TimedMessage class</secondary></indexterm> +<programlisting> +<![CDATA[ +>>-aTimedMessage~init(--msg-,-title-,-sleeping--+--------------+-+-----+--)---->< + +-,-earlyReply-+ +-,-p-+ + +]]> +</programlisting> + +<para>The init method prepares the dialog. </para> +<variablelist> +<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> +<listitem><para>The arguments are: +<variablelist> +<varlistentry><term>message</term> +<listitem><para>A string that is displayed inside the window as a message. The length +of the message determines the horizontal size of all standard dialogs. +</para></listitem></varlistentry> +<varlistentry><term>title</term> +<listitem><para>A string that is displayed as the window title in the title bar of the +dialog +</para></listitem></varlistentry> +<varlistentry><term>sleeping</term> +<listitem><para>A number that determines how long (in milliseconds) the window +is shown. If this number is 0 or greater, the message window is shown for that +time and automatically dismisses itself. The programmer need take no further +action. +</para> +<para>If the number is less than 0 then the message window is shown +indefinitely. The <computeroutput>execute</computeroutput> method returns +immediately. In this case, the programmer needs to dismiss the window manually. +This is done by invoking the <computeroutput>ok</computeroutput> method. See +<emphasis role="bold">Example 2</emphasis> below. +</para></listitem></varlistentry> +<varlistentry><term>earlyReply</term> +<listitem><para>The optional early reply argument defaults to false. If used +and if true, the <computeroutput>execute</computeroutput> method of the dialog +returns immediately. This allows the code at the point where <computeroutput> +execute</computeroutput> was invoked to continue. The message windows continues +to display for its specified duration and then dismisses itself automatically. +</para></listitem></varlistentry> +<varlistentry><term>p [optional]</term> +<listitem> +<para> + A <xref linkend="clsPoint"/> object that specifies the position, in pixels, for the position of the timed + message dialog on the screen. By default the dialog is centered in the screen. If <emphasis role="italic">p</emphasis> + is used, the point specifies the position of the upper left corner of the dialog. +</para> +</listitem></varlistentry> +</variablelist> +</para></listitem></varlistentry> +<varlistentry id="example1TimedMessage"><term><emphasis role="bold">Example + 1:</emphasis></term> +<listitem><para>The following example shows a window with the title of <emphasis +role="italic">Infomation</emphasis> for a duration of 3 seconds: +<programlisting> +<![CDATA[ +dlg = .TimedMessage~New("Application will be started, please wait", - + "Information", 3000) +dlg~execute +drop dlg +]]> +</programlisting> +</para></listitem></varlistentry> +<varlistentry id="example2TimedMessage"><term><emphasis role="bold">Example +2:</emphasis></term> +<listitem><para>The following example shows an introductory window that displays +while an application is doing its time consuming start up routine. Since this +start up process can vary in time depending on the individual system, the window +is set to display indefinitely. When the start up process is finished, the +programmer dismisses the window and destroys the dialog manually. +<programlisting> +<![CDATA[ +dlg = .TimedMessage~New("The WidgetCreator Application - loading ...", - + "The Widget Factory", -1) +dlg~execute +ret = doStartup() +dlg~ok +drop dlg +if ret <> 0 then do + ... +end +]]> +</programlisting> +</para></listitem></varlistentry> +<varlistentry id="example3TimedMessage"><term><emphasis role="bold">Example +3:</emphasis></term> +<listitem><para>The following example is a variation on <emphasis role="bold"> +Example 2</emphasis>. In this case the Widget Factory executives decided that +they want their WidgeCreator splash screen to always display for 2 seconds to +the customer and then close. The early reply argument is used so that the start +up routine executes immediately. After 2 seconds the splash screen dismisses +and the dialog is destroyed automatically. +</para> +<note><title>Note</title><para>It is not necessary to explicitly drop the dlg +variable. That is shown in the other examples to emphasize the point that the +dialog has been destroyed.</para></note> +<programlisting> <![CDATA[ +dlg = .TimedMessage~New("The WidgetCreator Application - loading ...", - + "The Widget Factory", 2000) +dlg~execute +if doStartup() <> 0 then do + ... +end +]]> +</programlisting></listitem></varlistentry> +</variablelist> </section> +<section id="defDlgTimedMessage"><title>defineDialog</title> +<indexterm><primary>Define</primary> +<secondary>TimedMessage</secondary></indexterm> +<programlisting> +<![CDATA[ +>>-aTimedMessage~DefineDialog---------------------------------->< +]]> +</programlisting> + +<para>The defineDialog method is called by the create method of the parent +class, PlainUserDialog, which in turn is called at the very beginning of +Execute. You do not have to call it. However, you may want to over-ride it in +your subclass to add more dialog controls to the window. If you over-ride it, +you have to forward the message to the parent class by using the keyword super. +</para> +<variablelist> +<varlistentry><term><emphasis role="bold">Example:</emphasis></term> +<listitem><para>The following example shows how to subclass the TimedMessage +class and how to add a background bitmap to the dialog window: +<programlisting> +<![CDATA[ +::class MyTimedMessage subclass TimedMessage inherit DialogExtensions + +::method defineDialog + self~backgroundBitmap("mybackg.bmp", "USEPAL") + self~DefineDialog:super() +]]> +</programlisting> +</para></listitem></varlistentry> +</variablelist> +</section> + +<section id="h002097"><title>execute</title> +<indexterm><primary>execute</primary> +<secondary>TimedMessage class</secondary></indexterm> +<programlisting> +<![CDATA[ +>>-aTimedMessage~Execute--------------------------------------->< +]]> +</programlisting> + +<para> + The execute method creates and shows the message window. If the specified <link linkend="initTimedMessage">duration</link> + is not negative, this method destroys the dialog automatically when the duration is up. If the duration is less than 0, + then the programmer must destroy the dialog manually by invoking the <computeroutput>ok</computeroutput> method. See this + <link linkend="example2TimedMessage">example</link> for a code snippet showing the procedure. +</para> +</section> + +</section> + +</section> + + <section id="sctPublicRoutines"><title>Public Routines</title> <indexterm><primary>ooDialog public routines</primary></indexterm> <para> @@ -1072,6 +1107,494 @@ </programlisting> </para> +<section id="rtnAskDialog" xreflabel="AskDialog"><title>AskDialog Routine</title> +<indexterm><primary>AskDialog</primary></indexterm> +<indexterm><primary>public routines</primary> +<secondary>AskDialog</secondary></indexterm> +<para>Pops up a message box containing the specified text, a Yes button, and +a No Button.</para> +<programlisting> +<![CDATA[ +>>-AskDialog(--question--+-------------------+--)------------->< + +--, defaultbutton--+ + +]]> +</programlisting> + +<para></para> +<variablelist> +<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> +<listitem><para>The only argument is: +<variablelist> +<varlistentry><term>question</term> +<listitem><para>Text to be displayed in the message box. +</para></listitem></varlistentry> +<varlistentry><term>defaultbutton</term> +<listitem><para>Specifies which button, the Yes or the No button, has the +default focus when the message box pops up. This argument can be Yes or No and +is optional. If the argument is omitted, the Yes button will be given the focus. +Only the first letter of the option is needed and case is not significant. +</para></listitem></varlistentry> +</variablelist> +</para></listitem></varlistentry> +<varlistentry><term>Return Values:</term> +<listitem><para> +<variablelist> +<varlistentry><term>0</term> +<listitem><para>The No button has been selected. +</para></listitem></varlistentry> +<varlistentry><term>1</term> +<listitem><para>The Yes button has been selected. +</para></listitem></varlistentry> +</variablelist> +</para></listitem></varlistentry> +</variablelist> +</section> + +<section id="rtnCheckList" xreflabel="CheckList"><title>CheckList Routine</title> +<indexterm><primary>CheckList</primary> +<secondary>function</secondary></indexterm> +<indexterm><primary>public routines</primary> +<secondary>CheckList</secondary></indexterm> +<para>A shortcut function to invoke the <xref linkend="clsCheckList"/> +dialog: </para> + +<programlisting> +<![CDATA[ +>>--CheckList(--message--,--title--,--labels--,-+-----------+----> + +-,--checks-+ + +>---+------------------------+--)------------------------------->< + +-,--+-----+--+--------+-+ + +-len-+ +-,--max-+ + + +]]> +</programlisting> + +<variablelist> +<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> +<listitem> +<para> + The arguments are similar to what is described in the <xref linkend="initCheckList"/>) method of the + <computeroutput>CheckList</computeroutput> class. However, instead of stems, arrays are passed into and returned from the + function. +<variablelist> +<varlistentry><term>message</term> +<listitem><para>A text string that is displayed on top of the check box group. +It could be used, for example, to give the user a hint as to what to do. +</para></listitem></varlistentry> +<varlistentry><term>title</term> +<listitem><para>A text string for the dialog's title +</para></listitem></varlistentry> +<varlistentry><term>labels</term> +<listitem><para>An array containing the labels, in order, for each of the check +boxes. The dialog will contain a check box for each label. +</para></listitem></varlistentry> +<varlistentry><term>checks</term> +<listitem><para>This argument is an array that allows you to pre-check any of +the check boxes. For each index in this array whose item is <computeroutput> +.true</computeroutput>, (or 1,) the check box at the corresponding index in the +<computeroutput>labels</computeroutput> array will be checked. For any index +that is not <computeroutput>.true </computeroutput>, the corresponding check box +will not be checked. This means that the programmer only needs to put a +<computeroutput>.true</computeroutput> at the indexes where he wants the check +boxes checked. All the other indexes can be left empty. +</para></listitem></varlistentry> +<varlistentry><term>len</term> +<listitem><para>Determines the length (in dialog units) of the check boxes and +labels. If omitted, the size is calculated to fit the largest label. +</para></listitem></varlistentry> +<varlistentry><term>max</term> +<listitem><para>The maximum number of check boxes in one column. If there are +more check boxes than max, that is, if labels has more items than the value of +max, the check boxes will be put into columns. Each column will contain no more +than the number of check boxes specified by max. +</para></listitem></varlistentry> +</variablelist> +</para></listitem></varlistentry> +<varlistentry><term><emphasis role="bold">Return value:</emphasis></term> +<listitem><para>If the user cancels the dialog, then <computeroutput>.nil +</computeroutput> is returned. If the user clicks the okay button, then an +array is returned. The array will be the same size as the input +<computeroutput>labels</computeroutput> array. Each index of the returned array +will contain <computeroutput>.true</computeroutput> if the corresponding check +box was checked by the user or will contain <computeroutput>.false +</computeroutput> if the check box was not checked. +</para></listitem></varlistentry> +<varlistentry><term><emphasis role="bold">Example</emphasis></term> +<listitem><para>The following example show how to use the +<computeroutput>CheckList</computeroutput> public routine: + +<programlisting> +<![CDATA[ + + weekdays = .array~of("Monday","Tuesday","Wednesday","Thursday", - + "Friday","Saturday","Sunday") + + -- Monday and Tuesday will be checked, all the rest will not be checked. + checks = .array~of(.true, .true, .false) + checks[5] = 0 + checks[7] = 'a' + + -- The labels will be 60 dialog units wide and there will be at most 4 check + -- boxes in a column. (Only 7 check boxes, so 2 columns, the first with 4 + -- check boxes, the second with 3.) + + days = CheckList("Check the days", "Working Days", weekdays, checks, 60, 4) + + if days <> .Nil then do i = 1 to days~items + if days[i] then say "Working day =" weekdays[i] + end + +::requires "ooDialog.cls" + +]]> +</programlisting> + +</para></listitem></varlistentry> +</variablelist> +</section> + +<section id="rtnErrorDialog" xreflabel="ErrorDialog"><title>ErrorDialog Routine</title> +<indexterm><primary>ErrorDialog</primary></indexterm> +<indexterm><primary>public routines</primary> +<secondary>ErrorDialog</secondary></indexterm> +<para>Pops up a message box containing the specified text, an OK button, and +an error symbol.</para> +<programlisting> +<![CDATA[ +>>-ErrorDialog(--error_text--)-------------------------------->< +]]> +</programlisting> + +<para></para> +<variablelist> +<varlistentry><term><emphasis role="bold">Argument:</emphasis></term> +<listitem><para>The only argument is: +<variablelist> +<varlistentry><term>error_text</term> +<listitem><para>Text to be displayed in the message box. +</para></listitem></varlistentry> +</variablelist> +</para></listitem></varlistentry> +</variablelist> +</section> + +<section id="rtnFileNameDialog" xreflabel="FileNameDialog"><title>FileNameDialog Routine</title> +<indexterm><primary>FilenameDialog</primary></indexterm> +<indexterm><primary>public routines</primary><secondary>FileNameDialog</secondary></indexterm> +<programlisting> +<![CDATA[ +>>-FileNameDialog(-+-----+-+----------+-+-------+-+--------+-+---------+--> + +-sel-+ +-,-parent-+ +-,-msk-+ +-,-type-+ +-,-title-+ + +>-----------------+----------+-+---------+-+-----------+--)--------------->< + +-,-defExt-+ +-,-multi-+ +-,-sepChar-+ + + +]]> +</programlisting> + +<para> + Causes a file selection dialog box to appear. File selection dialogs are used to allow the user to pick a file or set + of files to open, or to pick a file to save to. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The arguments are: + <variablelist> + <varlistentry><term>sel [optional]</term> + <listitem> + <para> + This argument can be used to pre-select a file and / or have the open or save dialog start in a specified + directory. + </para> + <para> + This argument initializes the open or save dialog by selecting the specified file and placing its name in the + <emphasis role="italic">File</emphasis> edit control of the dialog. In addition this argument can also be used to + specify the initial directory (folder) the dialog opens in. + </para> + <para> + When this argument contains no path information, then the <emphasis role="italic">File</emphasis> name edit + control will contain the argument and the initial directory is determined by the operating system. Which + directory the operating system picks varies slightly between versions of Windows. But, in general, it will be a + directory previously used in one of the Windows common dialogs, or a directory in the users My Documents folder. + </para> + <para> + If the argument contains file name and path information, the initial directory will be determined by the path + information and the <emphasis role="italic">File</emphasis> name edit control will contain the file information. + When the selfile argument contains only path information and no file name information, i.e. the + argument ends with a back slash <emphasis role="italic">\</emphasis>, then the initial directory will be that + path and the <emphasis role="italic">File</emphasis> name edit control will be left blank. + </para> + <para> + In cases where the argument contains incorrect path information, the initial directory is determined as if no path + information had been supplied and the entire value of the argument is placed in the File name field. + </para> + <para> + <emphasis role="bold">Note</emphasis> that Windows treats normal wild card characters as valid for file names. + Therefore, values such as <emphasis role="italic">C:\*.*</emphasis> or <emphasis + role="italic">C:\Windows\*.exe</emphasis> are acceptable for this argument. + </para> + </listitem></varlistentry> + <varlistentry><term>parent [optional]</term> + <listitem> + <para> + The window <xref linkend="defHandle"/> of a parent window for the open or save file dialog. Normally + the programmer would use the handle of a dialog in her program. The operating system disables the parent window + until the user closes the open or save dialog. + </para> + </listitem></varlistentry> + <varlistentry>... [truncated message content] |
From: <mie...@us...> - 2012-12-11 23:55:40
|
Revision: 8679 http://sourceforge.net/p/oorexx/code-0/8679 Author: miesfeld Date: 2012-12-11 23:55:36 +0000 (Tue, 11 Dec 2012) Log Message: ----------- ooDialog doc - continue incremental update Modified Paths: -------------- docs/trunk/oodialog/en-US/dataAttributes.xml docs/trunk/oodialog/en-US/listview.xml docs/trunk/oodialog/en-US/windowBase.xml Modified: docs/trunk/oodialog/en-US/dataAttributes.xml =================================================================== --- docs/trunk/oodialog/en-US/dataAttributes.xml 2012-12-11 20:15:40 UTC (rev 8678) +++ docs/trunk/oodialog/en-US/dataAttributes.xml 2012-12-11 23:55:36 UTC (rev 8679) @@ -460,7 +460,7 @@ </para> <para> With auto detection on, the states of the dialog controls are set to the data (values) of the corresponding data - attributes. This is done <emphasis role="bold">after</emphasis><xref linkend="mthInitDialog"/> is + attributes. This is done <emphasis role="bold">after</emphasis> <xref linkend="mthInitDialog"/> is invoked. The consequence of this is that, if the programmer explicitly sets the state of the dialog controls in the <emphasis role="italic">initDialog</emphasis>() method, the ooDialog framwork will then <emphasis role="bold">reset</emphasis> the state of all the dialog controls afterwards. This can be disconcerting to the Modified: docs/trunk/oodialog/en-US/listview.xml =================================================================== --- docs/trunk/oodialog/en-US/listview.xml 2012-12-11 20:15:40 UTC (rev 8678) +++ docs/trunk/oodialog/en-US/listview.xml 2012-12-11 23:55:36 UTC (rev 8679) @@ -192,7 +192,7 @@ </row> <row> <entry><link linkend="clsLvFullRow">LvFullRow</link></entry> -<entry>The <computeroutput>LvFullRow</computeroutput> class represents a single item and its subitems in a list-view and contains the completed set of data pertaining to that item.</entry> +<entry>The <computeroutput>LvFullRow</computeroutput> class represents a single item and its subitems in a list-view and contains the complete set of data pertaining to that item.</entry> </row> <row> <entry><link linkend="clsLvItem">LvItem</link></entry> @@ -203,6 +203,14 @@ <entry>The <computeroutput>LvSubItem</computeroutput> class represents a single subitem of a list-view item and the data for that subitem.</entry> </row> <row> +<entry align="center"><emphasis role="bold">Constant Methods</emphasis></entry> +<entry align="center"><emphasis role="bold">Constant Methods</emphasis></entry> +</row> +<row> +<entry><link linkend="sctListViewConstantMethods">Constant Methods</link></entry> +<entry>The <computeroutput>ListView</computeroutput> class provides several <emphasis role="italic">constant</emphasis> values through the <computeroutput>::constant</computeroutput>directive.</entry> +</row> +<row> <entry align="center"><emphasis role="bold">Instance Methods</emphasis></entry> <entry align="center"><emphasis role="bold">Instance Methods</emphasis></entry> </row> @@ -220,7 +228,7 @@ </row> <row> <entry><xref linkend="mthAddRow"/></entry> -<entry>Adds a new item to a list-view.</entry> +<entry>Adds a new item to this list-view.</entry> </row> <row> <entry><xref linkend="mthAddStyleClsListView"/></entry> @@ -244,11 +252,11 @@ </row> <row> <entry><xref linkend="mthBkColorEquals"/></entry> -<entry>Sets the background color of a list view-control.</entry> +<entry>Sets the background color of this list-view control.</entry> </row> <row> <entry><xref linkend="mthCheckClsListControl"/></entry> -<entry>Sets the check mark for this list-view item.</entry> +<entry>Sets the check mark for a single list-view item.</entry> </row> <row> <entry><xref linkend="mthCheckAll"/></entry> @@ -280,11 +288,11 @@ </row> <row> <entry><xref linkend="mthDeselect"/></entry> -<entry>Deselects an item in the list-view.</entry> +<entry>Deselects an item in this list-view.</entry> </row> <row> <entry><xref linkend="mthDeselectAll"/></entry> -<entry>Deselects all items in the list-view.</entry> +<entry>Deselects all items in this list-view.</entry> </row> <row> <entry><xref linkend="mthDropHighLighted"/></entry> @@ -300,7 +308,7 @@ </row> <row> <entry><xref linkend="mthEnsureVisible"/></entry> -<entry>Ensures that a list-view item is entirely or partially visible by scrolling the list-view control, if necessary.</entry> +<entry>Ensures that a list-view item is entirely or partially visible by scrolling this list-view control, if necessary.</entry> </row> <row> <entry><xref linkend="mthFindClsListView"/></entry> @@ -356,7 +364,7 @@ </row> <row> <entry><xref linkend="mthGetExtendedStyleRaw"/></entry> -<entry>Returns the extended styles of this list-view cont control as the numeric value of the extended style flags.</entry> +<entry>Returns the extended styles of this list-view control as the numeric value of the extended style flags.</entry> </row> <row> <entry><xref linkend="mthGetFullRow"/></entry> @@ -372,7 +380,7 @@ </row> <row> <entry><xref linkend="mthGetItem"/></entry> -<entry>Returns some, or all, of the information the list-view maintains on the specified item. The information is returned as a <link linkend="clsLvItem">LvItem</link> object. The item is specified by either a <computeroutput>LvItem</computeroutput> object or by the item's index.</entry> +<entry>Returns some, or all, of the information this list-view maintains on the specified item. The information is returned as a <link linkend="clsLvItem">LvItem</link> object. The item is specified by either a <computeroutput>LvItem</computeroutput> object or by the item's index.</entry> </row> <row> <entry><xref linkend="mthGetItemDataClsListView"/></entry> @@ -472,11 +480,11 @@ </row> <row> <entry><xref linkend="mthModifyItem"/></entry> -<entry>xxx</entry> +<entry>Modifies some or all of the data this list-view maintains for an item using a <xref linkend="clsLvItem"/> object.</entry> </row> <row> <entry><xref linkend="mthModifySubitem"/></entry> -<entry>xxx</entry> +<entry>Modifies some or all of the data this list-view maintains for a subitem of an item using a <xref linkend="clsLvSubItem"/> object.</entry> </row> <row> <entry><xref linkend="mthNext"/></entry> @@ -500,7 +508,7 @@ </row> <row> <entry><link linkend="mthPrependFullRow">prependFullRow</link></entry> -<entry>Adds a new item to this list-view at the beginning of the list using a <link linkend="clsLvFullRow">LvFullRow</link> object.</entry> +<entry>Adds an item to this list-view at the first position in the list using a <xref linkend="clsLvFullRow"/> object.</entry> </row> <row> <entry><xref linkend="mthPrevious"/></entry> @@ -651,6 +659,63 @@ </section> +<section id="sctListViewConstantMethods"><title>Constant Methods</title> +<indexterm><primary>constant methods</primary><secondary>ListView class</secondary></indexterm> +<indexterm><primary>ListView class</primary><secondary>constant methods</secondary></indexterm> +<para> + The <computeroutput>ListView</computeroutput> class provides the following <emphasis role="italic">constant</emphasis> + values through the use of the <computeroutput>::constant</computeroutput> directive. +</para> +<table id="tblConstantsListview" frame="all"> <title>ListView Class Constant Reference</title> +<tgroup cols="2"> +<colspec colwidth="1*" /><colspec colwidth="3*" /> +<thead> +<row> +<entry>Constant Symbol</entry> +<entry>Description</entry> +</row> +</thead> +<tbody> +<row> +<entry>GROUPIDCALLBACK</entry> +<entry>A group ID index value that indicates the list-view control should send the GETDISPINFO notification message to retrieve the item's group index.</entry> +</row> +<row> +<entry>GROUPIDNONE</entry> +<entry>A group ID value that indicates the list-view item does not belong to a group.</entry> +</row> +<row> +<entry>IMAGECALLBACK</entry> +<entry>An index value for the item's icon in the control's image list that indicates the list-view control should send the GETDISPINFO notification message to retrieve the item's icon index when it needs to display the image.</entry> +</row> +<row> +<entry>IMAGENONE</entry> +<entry>An index value for the item's icon in the control's image list that indicates the list-view item does not have an icon.</entry> +</row> +<row> +<entry>LVCFMT_FILL</entry> +<entry><emphasis role="bold">Requires Windows Vista or later</emphasis>. Fill the remainder of the tile area. Might have a title. Only valid in extended tile view. The LVCFMT_FILL flag forces the column to fill the remainder of the tile area.</entry> +</row> +<row> +<entry>LVCFMT_LINE_BREAK</entry> +<entry><emphasis role="bold">Requires Windows Vista or later</emphasis>. Move to the top of the next list of columns. Only valid in extend tile view, The LVCFMT_LINE_BREAK flag forces the column to wrap to the top of the next list of columns.</entry> +</row> +<row> +<entry>LVCFMT_NO_TITLE</entry> +<entry><emphasis role="bold">Requires Windows Vista or later</emphasis>. This subitem does not have a title. Only valid in extended tile view. The LVCFMT_NO_TITLE flag indicates that the column should not display a title.</entry> +</row> +<row> +<entry>LVCFMT_TILE_PLACEMENTMASK</entry> +<entry><emphasis role="bold">Requires Windows Vista or later</emphasis>. This is a combination of the LVCFMT_LINE_BREAK and LVCFMT_FILL constants.</entry> +</row> +<row> +<entry>LVCFMT_WRAP</entry> +<entry><emphasis role="bold">Requires Windows Vista or later</emphasis>. This subitem can be wrapped. Only valid in extended tile view. The LVCFMT_WRAP flag allows the column to wrap within the remaining space in its list of columns.</entry> +</row> +</tbody></tgroup> +</table> +</section> + <section id="tmthNewListView" xreflabel="newListview"><title>newListView (dialog object method)</title> <para> List view objects can not be instantiated by the programmer from Rexx code. Rather a list-view object is obtained @@ -1150,7 +1215,7 @@ <![CDATA[ +-,----+ V | ->>--addRow(--+------+--,--------+--+--------+--)--->< +>>--addRow(--+------+--,--------+--+--------+--)->< +-item-+ +-,-icon-+ +-,-text-+ ]]> </programlisting> @@ -1413,7 +1478,7 @@ <secondary>ListView class</secondary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~check(--index--)-------------------------------------------->< +>>-aListControl~check(--index--)----------------->< ]]> </programlisting> @@ -1481,7 +1546,7 @@ <indexterm><primary>checkAll</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~CheckAll---------------------------------------------------->< +>>-aListControl~CheckAll------------------------->< ]]> </programlisting> @@ -1532,7 +1597,7 @@ <indexterm><primary>columnInfo</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~columnInfo(--column--)------------------------->< +>>-aListControl~columnInfo(--column--)----------->< ]]> @@ -1576,7 +1641,7 @@ <indexterm><primary>columnWidth</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~columnWidth(--column--)------------------------>< +>>-aListControl~columnWidth(--column--)---------->< ]]> @@ -1832,7 +1897,7 @@ <indexterm><primary>deselect</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~deselect(--item--)----------------------------->< +>>-aListControl~deselect(--item--)--------------->< ]]> @@ -1912,7 +1977,7 @@ <secondary>ListView class</secondary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~DropHighlighted-------------------------------->< +>>-aListControl~DropHighlighted------------------>< ]]> @@ -1932,7 +1997,7 @@ <secondary>ListView class</secondary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~edit(--item--)--------------------------------->< +>>-aListControl~edit(--item--)------------------->< ]]> @@ -1961,7 +2026,7 @@ <secondary>ListView class</secondary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~EndEdit---------------------------------------->< +>>-aListControl~EndEdit-------------------------->< ]]> @@ -2269,7 +2334,7 @@ <secondary>ListView class</secondary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~focus(--item--)-------------------------------->< +>>-aListControl~focus(--item--)------------------>< ]]> @@ -2309,7 +2374,7 @@ <secondary>ListView class</secondary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~Focused---------------------------------------->< +>>-aListControl~Focused-------------------------->< ]]> @@ -2328,7 +2393,7 @@ <indexterm><primary>getCheck</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~getCheck(--index--)----------------------------------------->< +>>-aListControl~getCheck(--index--)-------------->< ]]> </programlisting> @@ -2397,7 +2462,7 @@ <secondary>ListView class</secondary></indexterm> <programlisting> <![CDATA[ ->>--getColumnCount---------------------------------------------------->< +>>--getColumnCount------------------------------->< ]]> </programlisting> @@ -2559,7 +2624,7 @@ <secondary>ListView class</secondary></indexterm> <programlisting> <![CDATA[ ->>--getColumnOrder---------------------------------------------------->< +>>--getColumnOrder------------------------------->< ]]> </programlisting> @@ -2720,7 +2785,7 @@ <indexterm><primary>getExtendedStyle</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~GetExtendedStyle--------------------------------------------->< +>>-aListControl~GetExtendedStyle----------------->< ]]> </programlisting> @@ -2818,7 +2883,7 @@ <indexterm><primary>getExtendedStyleRaw</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~GetExtendedStyleRaw------------------------------------------>< +>>-aListControl~GetExtendedStyleRaw-------------->< ]]> </programlisting> @@ -3076,7 +3141,7 @@ <secondary>ListView class</secondary></indexterm> <programlisting> <![CDATA[ ->>--getImageList(--+--------+--)------------------------------------>< +>>--getImageList(--+--------+--)----------------->< +--type--+ ]]> </programlisting> @@ -4263,7 +4328,7 @@ <varlistentry><term>txt [required]</term> <listitem> <para> - The text, the label, for the column + The text, the label, for the column. The text for the column must be less than 256 characters long. </para> </listitem></varlistentry> <varlistentry><term>width [required]</term> @@ -4314,10 +4379,11 @@ <varlistentry><term>adjustFullRows [optional]</term> <listitem> <para> - If true attempts to fix up the <xref linkend="clsLvFullRow"/> objects assigned to the item <link - linkend="mthSetItemDataClsListView">data</link> of each list-view item. Does nothing if false. The default is false. - This argument is only used to support <link linkend="sctInternalSorting">internal</link> sorting. If the application is - not using internal sorting then this argument should just be ignored. + If <emphasis role="italic">adjustFullRows</emphasis> is true, the ooDialog framework attempts to fix up the <xref + linkend="clsLvFullRow"/> objects assigned to the item <link linkend="mthSetItemDataClsListView">data</link> of each + list-view item. Nothing is done if the arguemnt is false. The default is false. This argument is only used to support + <link linkend="sctInternalSorting">internal</link> sorting. If the application is not using internal sorting then this + argument should just be ignored. </para> </listitem></varlistentry> </variablelist> @@ -4334,7 +4400,7 @@ If <emphasis role="italic">colIdx</emphasis> is greater than the current number of columns then the method does not fail. Rather, the operating system adds the column as the last column rather that at the index specified. I.e., if there currently are 2 columns, (column 0 and column 1,) and <emphasis role="italic">colIndex</emphasis> is 3, the - operating system adds the column at index 2 rathr than index 3. + operating system adds the column at index 2 rather than index 3. </para> <para> Only use the <emphasis role="italic">adjustFullRows</emphasis> argument to adjust the @@ -4373,6 +4439,7 @@ <listitem> <para> The arguments are: + </para> <variablelist> <varlistentry><term>colIdx [optional]</term> <listitem> @@ -4384,7 +4451,7 @@ <varlistentry><term>txt [required]</term> <listitem> <para> - The text (label) for the column. + The text (label) for the column. The text for the column must be less than 256 characters long. </para> </listitem></varlistentry> <varlistentry><term>width [required]</term> @@ -4431,14 +4498,14 @@ <varlistentry><term>adjustFullRows [optional]</term> <listitem> <para> - If true attempts to fix up the <xref linkend="clsLvFullRow"/> objects assigned to the item <link - linkend="mthSetItemDataClsListView">data</link> of each list-view item. Does nothing if false. The default is false. - This argument is only used to support <link linkend="sctInternalSorting">internal</link> sorting. If the application is - not using internal sorting then this argument should just be ignored. + If <emphasis role="italic">adjustFullRows</emphasis> is true, the ooDialog framework attempts to fix up the <xref + linkend="clsLvFullRow"/> objects assigned to the item <link linkend="mthSetItemDataClsListView">data</link> of each + list-view item. Nothing is done if the arguemnt is false. The default is false. This argument is only used to support + <link linkend="sctInternalSorting">internal</link> sorting. If the application is not using internal sorting then this + argument should just be ignored. </para> </listitem></varlistentry> </variablelist> - </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> @@ -4449,15 +4516,14 @@ <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - The text for the column must be less than 256 characters long. The inserted columns are only visible when the - list-view is in report view, but, columns can be inserted into the list-view control when it is in any view. + The inserted columns are only visible when the list-view is in report view, but, columns can be inserted into the + list-view control when it is in any view. </para> <para> This method and the <xref linkend="mthInsertColumn"/> method are virtually the same, except that in this method the width of the column is specified in pixels. The <emphasis role="italic">insertColumn</emphasis> - method takes dialog units for the width and then converts them to pixels using - <xref linkend="ovvInaccurate"/>. This makes the width used by the <emphasis - role="italic">insertColumn</emphasis> method inaccurate. + method takes dialog units for the width and then converts them to pixels using an <xref linkend="ovvInaccurate"/> method. + This makes the width used by the <emphasis role="italic">insertColumn</emphasis> method inaccurate. </para> <para> <emphasis role="bold">Note</emphasis> that previous versions of this documentation incorrectly stated that the @@ -4532,7 +4598,7 @@ When a full row object is used to add an item to the list view, all the subitems are also added. The <emphasis role="italic">insertFullRow</emphasis> method always inserts the item into the list at the position specified in the full row object. The item index in the subitems in the full row object are ignored. After the item is inserted, the - item index in the subitems is updated to the correct value of the newly added item. + item indexes in the subitems are updated to the correct value of the newly added item. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> @@ -4544,10 +4610,18 @@ <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example constructs a full row object and inserts it into the list-view. The row is inserted at index 120 of the + list-view: <programlisting> <![CDATA[ + lvItem = .LvItem~new(120, "Business manager", 6) + lvSub1 = .LvSubItem~new(120, 1, "Tom", 14) + lvSub2 = .LvSubItem~new(120, 2, "Sawyer", 26) + lvSub3 = .LvSubItem~new(120, 3, "ts...@go...", 11) + lvFullRow = .LvFullRow~new(lvItem, lvSub1, lvSub2, lvSub3, .true) + list~insertFullRow(lvFullRow) + ]]> </programlisting> </para> @@ -4560,7 +4634,7 @@ <secondary>ListView class</secondary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~isChecked(--index--)---------------------------------------->< +>>-aListControl~isChecked(--index--)------------->< ]]> </programlisting> @@ -4692,7 +4766,7 @@ <indexterm><primary>itemPos</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~itemPos(--item--)------------------------------>< +>>-aListControl~itemPos(--item--)---------------->< ]]> @@ -4730,7 +4804,7 @@ <secondary>ListView class</secondary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~Items------------------------------------------>< +>>-aListControl~Items---------------------------->< ]]> @@ -4749,7 +4823,7 @@ <indexterm><primary>itemsPerPage</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~ItemsPerPage----------------------------------->< +>>-aListControl~ItemsPerPage--------------------->< ]]> @@ -4771,7 +4845,7 @@ <indexterm><primary>itemState</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~itemState(--item--)---------------------------->< +>>-aListControl~itemState(--item--)-------------->< ]]> @@ -4847,7 +4921,7 @@ <secondary>ListView class</secondary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~Last------------------------------------------->< +>>-aListControl~Last----------------------------->< ]]> @@ -4866,7 +4940,7 @@ <indexterm><primary>lastSelected</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~LastSelected----------------------------------->< +>>-aListControl~LastSelected--------------------->< ]]> @@ -4900,83 +4974,88 @@ Remember that in a list-view, items and columns use a 0-based index. Subitems use a 1-based index. </para> <variablelist> -<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> -<listitem><para>The arguments are: -<variablelist> -<varlistentry><term>item</term> -<listitem> -<para> - The index of the item to be modified. If you omit this argument, the selected item is used. -</para> -</listitem></varlistentry> -<varlistentry><term>subitem</term> -<listitem><para> - This method works in a similar manner as the <xref linkend="mthInsertClsListControl"/>() - method. The use of the <emphasis role="italic">subitem</emphasis> argument controls whether the - <emphasis role="italic">text</emphasis> argument applies to the label of the item or the text of a - subitem. When <emphasis role="italic">subitem</emphasis> is omitted or 0, then the label of the item is - set to <emphasis role="italic">text</emphasis>. When <emphasis role="italic">subitem</emphasis> is - greater than 0, then the text of that subitem is set to <emphasis role="italic">text</emphasis>. -</para></listitem></varlistentry> -<varlistentry><term>text</term> -<listitem><para> - The new text for the item label, or the new text for the subitem of the item, depending on the value of - <emphasis role="italic">subitem</emphasis>. -</para></listitem></varlistentry> -<varlistentry><term>icon</term> -<listitem><para> - The new index of the icon for the item within the image list assigned to the list-view. Image lists are - assigned with the <xref linkend="mthSetImageListClsListView"/>() method. When - assigning the image list with <computeroutput>setImageList</computeroutput>(), use the LVSIL_NORMAL - flag for the icon view icons and the LVSIL_SMALL flag for the list, report, and small-icon view icons. -</para> -<para> - Use -1 or simply omit this argument to leave the icon index unchanged. If <emphasis - role="italic">subitem</emphasis> is greater than 0, this argument is ignored. -</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>The modification was successful. -</para></listitem></varlistentry> -<varlistentry><term>1</term> -<listitem><para>For all other cases. -</para></listitem></varlistentry> -</variablelist> -</para></listitem></varlistentry> -<varlistentry><term><emphasis role="bold">Example:</emphasis></term> -<listitem><para> - The following example modifies the icon for an item when it is activated. A method, - <computeroutput>onActivate</computeroutput>, is connected to the ACTIVATE notification. When an item is - activated it also gains the focus. The <computeroutput>onActivate</computeroutput>() method is invoked - when an item is activated, and the example determines which item was activated by seeing which item has - the focus. -<programlisting> -<![CDATA[ + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The arguments are: + </para> + <variablelist> + <varlistentry><term>item [optional]</term> + <listitem> + <para> + The index of the item to be modified. If this argument is omitted, the selected item is used. + </para> + </listitem></varlistentry> + <varlistentry><term>subitem [optional]</term> + <listitem> + <para> + This method works in a similar manner as the <xref linkend="mthInsertClsListControl"/>() + method. The use of the <emphasis role="italic">subitem</emphasis> argument controls whether the + <emphasis role="italic">text</emphasis> argument applies to the label of the item or the text of a + subitem. When <emphasis role="italic">subitem</emphasis> is omitted or 0, then the label of the item is + set to <emphasis role="italic">text</emphasis>. When <emphasis role="italic">subitem</emphasis> is + greater than 0, then the text of that subitem is set to <emphasis role="italic">text</emphasis>. + </para> + </listitem></varlistentry> + <varlistentry><term>text [required]</term> + <listitem> + <para> + The new text for the item label, or the new text for the subitem of the item, depending on the value of + <emphasis role="italic">subitem</emphasis>. + </para> + </listitem></varlistentry> + <varlistentry><term>icon [optional]</term> + <listitem> + <para> + The new index of the icon for the item within the image list assigned to the list-view. Image lists are + assigned with the <xref linkend="mthSetImageListClsListView"/>() method. When + assigning the image list with <computeroutput>setImageList</computeroutput>(), use the LVSIL_NORMAL + flag for the icon view icons and the LVSIL_SMALL flag for the list, report, and small-icon view icons. + </para> + <para> + Use -1 or simply omit this argument to leave the icon index unchanged. If <emphasis + role="italic">subitem</emphasis> is greater than 0, this argument is ignored. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + Returns 0 on success, 1 for all errors. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + The following example modifies the icon for an item when it is activated. A method, + <computeroutput>onActivate</computeroutput>, is connected to the ACTIVATE notification. When an item is activated it also + gains the focus. The <computeroutput>onActivate</computeroutput> method is invoked when an item is activated, and the + example determines which item was activated by seeing which item has the focus: -::method initDialog - expose list + <programlisting> + <![CDATA[ - list = self~newListView(IDC_LV_VIEWS) - self~connectListViewEvent(IDC_LV_VIEWS, 'ACTIVATE', 'onActivate') + ::method initDialog + expose list - ... + list = self~newListView(IDC_LV_VIEWS) + self~connectListViewEvent(IDC_LV_VIEWS, 'ACTIVATE', 'onActivate') -::method onActivate - expose list + ... - focusedItem = list~focused - text = list~itemText(focusedItem) + ::method onActivate + expose list - list~modify(focusedItem, , text, 2) + focusedItem = list~focused + text = list~itemText(focusedItem) -]]> -</programlisting> -</para></listitem></varlistentry> + list~modify(focusedItem, , text, 2) + + ]]> + </programlisting> + </para> + </listitem></varlistentry> </variablelist> </section> @@ -5160,25 +5239,25 @@ <indexterm><primary>ListView class</primary><secondary>modifyItem</secondary></indexterm> <programlisting> <![CDATA[ ->>--modifyItem(--+--------+--)--------------------------------------------->< - +--type--+ +>>--modifyItem(--lvItem--)----------------------->< ]]> </programlisting> <para> - xx + Modifies some or all of the data this list-view maintains for an item using a <xref linkend="clsLvItem"/> object. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The arguments are: + The single argument is: </para> <variablelist> - <varlistentry><term>TERM</term> + <varlistentry><term>lvItem [required]</term> <listitem> <para> - xx + A <computeroutput>LvItem</computeroutput> object that specifies which item to modify, what data to modify, and the new + data for the item. </para> </listitem></varlistentry> </variablelist> @@ -5186,33 +5265,64 @@ <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns true on success and false on error. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + The <xref linkend="atrIndexClsLvi"/> attribute of the <emphasis role="italic">lvItem</emphasis> object specifies which + item to modify. The <xref linkend="atrMaskClsLvi"/> and <xref linkend="atrItemStateMaskClsLvi"/> attributes specify + which attributes are valid, and the value of those attriubtes specifies the new data for the list-view item. </para> - </listitem></varlistentry> + <para> + For instance to modify the group ID and image index only of the list-view item at index 17, the programmer would use a + <computeroutput>LvItem</computeroutput> object and set the <emphasis role="italic">index</emphasis> attribute to 17, set + the <emphasis role="italic">mask</emphasis> attribute to GROUPID IMAGE, set the GroupID attribute to the new value for + the group ID, and set the <emphasis role="italic">imageIndex</emphasis> to the new index for the image. + </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> <listitem> <para> Raises syntax errors when incorrect usage is detected. </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example shows the process outlined in the remarks section for changing some information for the list-view item at + index 17: <programlisting> <![CDATA[ + lvItem = .LvItem~new(17) + lvItem~imageIndex = 8 + lvItem~groupID = 101 + lvItem~mask = "GROUPID IMAGE" + + list = self~newListView(IDC_LV_CLIENTS) + + list~modifyItem(lvItem) + ]]> </programlisting> + Note that the <computeroutput>LvItem</computeroutput> class will automatically set the <emphasis + role="italic">mask</emphasis> attribute correctly as the attribute values are added. So, the above code could have simply + been: +<programlisting> +<![CDATA[ + + lvItem = .LvItem~new(17) + lvItem~imageIndex = 8 + lvItem~groupID = 101 + + list = self~newListView(IDC_LV_CLIENTS) + + list~modifyItem(lvItem) +]]> +</programlisting> + The <emphasis role="italic">mask</emphasis> attribute was set explicitly in the first example for clarity, to show that + only the image index and group ID would be modified. </para> </listitem></varlistentry> </variablelist> @@ -5224,25 +5334,26 @@ <indexterm><primary>ListView class</primary><secondary>modifySubitem</secondary></indexterm> <programlisting> <![CDATA[ ->>--modifySubitem(--+--------+--)--------------------------------------------->< - +--type--+ +>>--modifySubitem(--lvSubitem--)----------------->< ]]> </programlisting> <para> - xx + Modifies some or all of the data this list-view maintains for a subitem of an item using a <xref linkend="clsLvSubItem"/> + object. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The arguments are: + The single argument is: </para> <variablelist> - <varlistentry><term>TERM</term> + <varlistentry><term>lvSubitem [required]</term> <listitem> <para> - xx + A <computeroutput>LvSubItem</computeroutput> object that specifies which subitem to modify, what data to modify, and + the new data for the subitem. </para> </listitem></varlistentry> </variablelist> @@ -5250,13 +5361,16 @@ <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns true on success and false on error. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + To modify a subitem, set the <xref linkend="atrItemClsLvSi"/> and <xref linkend="atrSubItemClsLvSi"/> attributes of a + <computeroutput>LvSubItem</computeroutput> object to identify which subitem is to be modified. Then set the <xref + linkend="atrMaskClsLvSi"/> attribute to specify what values of the subitem are to be changed, and set either or both + of the <xref linkend="atrTextClsLvSi"/> and <xref linkend="atrImageIndexClsLvSi"/> attributes to the new information. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> @@ -5264,19 +5378,36 @@ <para> Raises syntax errors when incorrect usage is detected. </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example updates the image index of the second subitem in the list-view item with index 17. <programlisting> <![CDATA[ + lvSubitem = .LvSubItem~new(17, 2, , 16, 'IMAGE') + + list = self~newListView(IDC_LV_CLIENTS) + + list~modifySubitem(lvSubitem) ]]> </programlisting> + Note that the <xref linkend="mthNewClsLvSubItem"/> method of the <computeroutput>LvSubItem</computeroutput> will + automatically set the <emphasis role="italic">mask</emphasis> attribute correctly. So, the above code could have simply + been: +<programlisting> +<![CDATA[ + + lvSubitem = .LvSubItem~new(17, 2, , 16) + + list = self~newListView(IDC_LV_CLIENTS) + + list~modifySubitem(lvSubitem) +]]> +</programlisting> + The <emphasis role="italic">mask</emphasis> argument was used in the first example for clarity, to show that only the + image index would be modified. </para> </listitem></varlistentry> </variablelist> @@ -5288,7 +5419,7 @@ <secondary>ListView class</secondary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~next(--item--)--------------------------------->< +>>-aListControl~next(--item--)------------------->< ]]> @@ -5315,7 +5446,7 @@ <indexterm><primary>nextLeft</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~nextLeft(--item--)----------------------------->< +>>-aListControl~nextLeft(--item--)--------------->< ]]> @@ -5342,7 +5473,7 @@ <indexterm><primary>nextRight</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~nextRight(--item--)---------------------------->< +>>-aListControl~nextRight(--item--)-------------->< ]]> @@ -5369,7 +5500,7 @@ <indexterm><primary>nextSelected</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~nextSelected(--item--)------------------------->< +>>-aListControl~nextSelected(--item--)----------->< ]]> @@ -5397,7 +5528,7 @@ <indexterm><primary>prepare4nItems</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~prepare4nItems(--items--)---------------------->< +>>-aListControl~prepare4nItems(--items--)-------->< ]]> @@ -5438,23 +5569,22 @@ </programlisting> <para> - Adds an item to the list-view at the first position in the list using a <link linkend="clsLvFullRow">LvFullRows</link> - object. + Adds an item to this list-view at the first position in the list using a <xref linkend="clsLvFullRow"/> object. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> The single argument is: + </para> <variablelist> <varlistentry><term>row [required]</term> <listitem> <para> - A <link linkend="clsLvFullRow">LvFullRow</link> object that specifies the item to be added to the list-view. + A <computeroutput>LvFullRow</computeroutput> object that specifies the item to be added to the list-view. </para> </listitem></varlistentry> </variablelist> - </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> @@ -5466,9 +5596,9 @@ <listitem> <para> When a full row object is used to add an item to the list view, all the subitems are also added. The <emphasis - role="italic">prependFullRow</emphasis> method always as the first item in the list. Because of this, the item index - in the item and in the subitems in the full row object are ignored. After the item is inserted, the item index is - updated in the item and in the subitems is updated to the correct value of the newly added item. + role="italic">prependFullRow</emphasis> method always inserts the new item as the first item in the list. Because of + this, the item index in the item and in the subitems in the full row object are ignored. After the item is inserted, the + item index is updated in the item and in the subitems is updated to the correct value of the newly added item. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> @@ -5484,6 +5614,14 @@ <programlisting> <![CDATA[ + lvItem = .LvItem~new(0, "Business manager", 6) + lvSub1 = .LvSubItem~new(0, 1, "Tom", 14) + lvSub2 = .LvSubItem~new(0, 2, "Sawyer", 26) + lvSub3 = .LvSubItem~new(0, 3, "ts...@go...", 11) + + lvFullRow = .LvFullRow~new(lvItem, lvSub1, lvSub2, lvSub3, .true) + list~prependFullRow(lvFullRow) + ]]> </programlisting> </para> @@ -5496,7 +5634,7 @@ <secondary>ListView class</secondary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~previous(--item--)----------------------------->< +>>-aListControl~previous(--item--)--------------->< ]]> @@ -5523,7 +5661,7 @@ <indexterm><primary>previousSelected</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~previousSelected(--item--)--------------------->< +>>-aListControl~previousSelected(--item--)------->< ]]> @@ -6042,7 +6180,7 @@ <programlisting> <![CDATA[ +-0-+ +-0-+ ->>-aListControl~scroll(--+---+--,--+---+--)-------------------->< +>>-aListControl~scroll(--+---+--,--+---+--)------>< +-x-+ +-y-+ @@ -6088,7 +6226,7 @@ <secondary>ListView class</secondary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~select(--item--)------------------------------->< +>>-aListControl~select(--item--)----------------->< ]]> @@ -6126,7 +6264,7 @@ <secondary>ListView class</secondary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~Selected--------------------------------------->< +>>-aListControl~Selected------------------------->< ]]> @@ -6146,7 +6284,7 @@ <secondary>ListView class</secondary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~SelectedItems---------------------------------->< +>>-aListControl~SelectedItems-------------------->< ]]> @@ -6166,7 +6304,7 @@ <secondary>ListView class</secondary></indexterm> <programlisting> <![CDATA[ ->>--setColumnOrder(--order--)----------------------------------------->< +>>--setColumnOrder(--order--)-------------------->< ]]> </programlisting> @@ -6713,7 +6851,7 @@ </para> <para> For the <emphasis role="italic">sortItems</emphasis> method to work, every list-view item must have the item data set. - When <emphasis role="italic">sortItems</emphasis> is invoked to use the internal ooDialog framework to do the sorting, + When <emphasis role="italic">sortItems</emphasis> is invoked to have the ooDialog framework do the sorting internally, the item data object must be a <xref linkend="clsLvFullRow"/> object. </para> </listitem></varlistentry> @@ -7110,7 +7248,7 @@ <indexterm><primary>smallSpacing</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~SmallSpacing----------------------------------->< +>>-aListControl~SmallSpacing--------------------->< ]]> @@ -7129,7 +7267,7 @@ <indexterm><primary>snapToGrid</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~SnapToGrid------------------------------------->< +>>-aListControl~SnapToGrid----------------------->< ]]> @@ -7434,7 +7572,7 @@ <indexterm><primary>spacing</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~Spacing---------------------------------------->< +>>-aListControl~Spacing-------------------------->< ]]> @@ -7453,7 +7591,7 @@ <indexterm><primary>stringWidth</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~stringWidth(--text--)-------------------------->< +>>-aListControl~stringWidth(--text--)------------>< ]]> @@ -7528,7 +7666,7 @@ <indexterm><primary>textBkColor</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~TextBkColor------------------------------------>< +>>-aListControl~TextBkColor---------------------->< ]]> @@ -7548,7 +7686,7 @@ <indexterm><primary>textBkColor=</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~textBkColor=(--color--)------------------------>< +>>-aListControl~textBkColor=(--color--)---------->< ]]> @@ -7573,7 +7711,7 @@ <indexterm><primary>textColor</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~TextColor-------------------------------------->< +>>-aListControl~TextColor------------------------>< ]]> @@ -7593,7 +7731,7 @@ <indexterm><primary>textColor=</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~textColor=(--color--)-------------------------->< +>>-aListControl~textColor=(--color--)------------>< ]]> @@ -7631,7 +7769,7 @@ <secondary>ListView class</secondary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~uncheck(--index--)------------------------------------------>< +>>-aListControl~uncheck(--index--)--------------->< ]]> </programlisting> @@ -7708,7 +7846,7 @@ <indexterm><primary>uncheckAll</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~UncheckAll-------------------------------------------------->< +>>-aListControl~UncheckAll----------------------->< ]]> </programlisting> @@ -7759,7 +7897,7 @@ <indexterm><primary>updateItem</primary></indexterm> <programlisting> <![CDATA[ ->>-aListControl~updateItem(--item--)--------------------------->< +>>-aListControl~updateItem(--item--)------------->< ]]> @@ -8046,9 +8184,9 @@ <indexterm><primary>LvCustomDrawSimple class</primary><secondary>clrText</secondary></indexterm> <programlisting> <![CDATA[ ->>--clrText----------------------------------------------------->< +>>--clrText-------------------------------------->< ->>--clrText-=-varName------------------------------------------->< +>>--clrText-=-varName---------------------------->< ]]> </programlisting> @@ -8107,9 +8245,9 @@ <indexterm><primary>LvCustomDrawSimple class</primary><secondary>clrTextBk</secondary></indexterm> <programlisting> <![CDATA[ ->>--clrTextBk----------------------------------------------------->< +>>--clrTextBk------------------------------------>< ->>--clrTextBk-=-varName------------------------------------------->< +>>--clrTextBk-=-varName-------------------------->< ]]> </programlisting> @@ -8168,9 +8306,9 @@ <indexterm><primary>LvCustomDrawSimple class</primary><secondary>drawStage</secondary></indexterm> <programlisting> <![CDATA[ ->>--drawStage----------------------------------------------------->< +>>--drawStage------------------------------------>< ->>--drawStage-=-varName------------------------------------------->< +>>--drawStage-=-varName-------------------------->< ]]> </programlisting> @@ -8254,9 +8392,9 @@ <indexterm><primary>LvCustomDrawSimple class</primary><secondary>font</secondary></indexterm> <programlisting> <![CDATA[ ->>--font----------------------------------------------------->< +>>--font----------------------------------------->< ->>--font-=-varName------------------------------------------->< +>>--font-=-varName------------------------------->< ]]> </programlisting> @@ -8334,9 +8472,9 @@ <indexterm><primary>LvCustomDrawSimple class</primary><secondary>id</secondary></indexterm> <programlisting> <![CDATA[ ->>--id----------------------------------------------------->< +>>--id------------------------------------------->< ->>--id-=-varName------------------------------------------->< +>>--id-=-varName--------------------------------->< ]]> </programlisting> @@ -8400,9 +8538,9 @@ <indexterm><primary>LvCustomDrawSimple class</primary><secondary>item</secondary></indexterm> <programlisting> <![CDATA[ ->>--item----------------------------------------------------->< +>>--item----------------------------------------->< ->>--item-=-varName------------------------------------------->< +>>--item-=-varName------------------------------->< ]]> </programlisting> @@ -8471,9 +8609,9 @@ <indexterm><primary>LvCustomDrawSimple class</primary><secondary>itemData</secondary></indexterm> <programlisting> <![CDATA[ ->>--itemData----------------------------------------------------->< +>>--itemData------------------------------------->< ->>--itemData-=-varName------------------------------------------->< +>>--itemData-=-varName--------------------------->< ]]> </programlisting> @@ -8547,9 +8685,9 @@ <indexterm><primary>LvCustomDrawSimple class</primary><secondary>reply</secondary></indexterm> <programlisting> <![CDATA[ ->>--reply----------------------------------------------------->< +>>--reply---------------------------------------->< ->>--reply-=-varName------------------------------------------->< +>>--reply-=-varName------------------------------>< ]]> </programlisting> @@ -8619,9 +8757,9 @@ <indexterm><primary>LvCustomDrawSimple class</primary><secondary>subItem</secondary></indexterm> <programlisting> <![CDATA[ ->>--subItem----------------------------------------------------->< +>>--subItem-------------------------------------->< ->>--subItem-=-varName------------------------------------------->< +>>--subItem-=-varName---------------------------->< ]]> </programlisting> @@ -8700,6 +8838,12 @@ object reflect the values of the label, icon, state, etc., for the list-view item. </para> <para> + <computeroutput>LvItem</computeroutput> objects can be used to set or modify the values of a list-view item, or to receive + information about an item. In addition <computeroutput>LvItem</computeroutput> objects are used in <xref + linkend="clsLvFullRow"/> objects. Each <computeroutput>LvFullRow</computeroutput> object is composed of at least one + <computeroutput>LvItem</computeroutput> object. +</para> +<para> Note that ooDialog does not currently support some of the newer features in list-views. The <computeroutput>LvItem</computeroutput> class is part of the first steps to enhance ooDialog to support all the list-view features. The <computeroutput>LvItem</computeroutput> class has support for attributes that will become important in an @@ -8723,10 +8867,6 @@ </thead> <tbody> <row> -<entry><link linkend="sctLvItemConstantMethods">Constant Methods</link></entry> -<entry>The <computeroutput>LvItem</computeroutput> class provides several <emphasis role="italic">constant</emphasis> values through the <computeroutput>::constant</computeroutput>directive.</entry> -</row> -<row> <entry align="center"><emphasis role="bold">Class Methods</emphasis></entry> <entry align="center"><emphasis role="bold">Class Methods</emphasis></entry> </row> @@ -8740,31 +8880,31 @@ </row> <row> <entry><xref linkend="atrColumnFormatsClsLvi"/></entry> -<entry></entry> +<entry>An array of column format values specifying the format of each item in a column in Tile view.</entry> </row> <row> <entry><xref linkend="atrColumnsClsLvi"/></entry> -<entry></entry> +<entry>An array of column indexes specifying which columns are displayed for this item in Tile view, and the order of those columns.</entry> </row> <row> <entry><xref linkend="atrGroupIDClsLvi"/></entry> -<entry></entry> +<entry>Reflects the group ID of this item.</entry> </row> <row> <entry><xref linkend="atrImageIndexClsLvi"/></entry> -<entry></entry> +<entry>Reflects the index in the icon <link linkend="mthSetImageListClsListView">image</link> lists for this item.</entry> </row> <row> <entry><xref linkend="atrIndentClsLvi"/></entry> -<entry></entry> +<entry>Reflects the number of image widths to indent this item.</entry> </row> <row> <entry><xref linkend="atrIndexClsLvi"/></entry> -<entry></entry> +<entry>Reflects the index of this item in the list-view.</entry> </row> <row> <entry><xref linkend="atrItemDataClsLvi"/></entry> -<entry></entry> +<entry>Reflects the item data value for this item.</entry> </row> <row> <entry><xref linkend="atrItemStateClsLvi"/></entry> @@ -8795,43 +8935,6 @@ </para> </section> -<section id="sctLvItemConstantMethods"><title>Constant Methods</title> -<indexterm><primary>constant methods</primary><secondary>LvItem class</secondary></indexterm> -<indexterm><primary>LvItem class</primary><secondary>constant methods</secondary></indexterm> -<para> - The <computeroutput>LvItem</computeroutput> class provides the following <emphasis role="italic">constant</emphasis> - values through the use of the <computeroutput>::constant</computeroutput> directive. -</para> -<table id="tblConstantsLvItem" frame="all"> <title>LvItem Class Constant Reference</title> -<tgroup cols="2"> -<colspec colwidth="1*" /><colspec colwidth="3*" /> -<thead> -<row> -<entry>Constant Symbol</entry> -<entry>Description</entry> -</row> -</thead> -<tbody> -<row> -<entry>GROUPIDCALLBACK</entry> -<entry>A group ID index value that indicates the list-view control should send the GETDISPINFO notification message to retrieve the item's group index.</entry> -</row> -<row> -<entry>GROUPIDNONE</entry> -<entry>A group ID value that indicates the list-view item does not belong to a group.</entry> -</row> -<row> -<entry>IMAGECALLBACK</entry> -<entry>An index value for the item's icon in the control's image list that indicates the list-view control should send the GETDISPINFO notification message to retrieve the item's icon index when it needs to display the image.</entry> -</row> -<row> -<entry>IMAGENONE</entry> -<entry>An index value for the item's icon in the control's image list that indicates the list-view item does not have an icon.</entry> -</row> -</tbody></tgroup> -</table> -</section> - <section id="mthNewClsLvItem" xreflabel="new"><title>new (Class Method)</title> <indexterm><primary>new</primary><secondary>LvItem class</secondary></indexterm> <indexterm><primary>LvItem class</primary><secondary>new</secondary></indexterm> @@ -8886,9 +8989,9 @@ <listitem> <para> The zero-based index of the item's icon in the control's <link linkend="mthSetImageListClsListView">image</link> list. - This applies to both the large and small image list. The <emphasis role="italic">imageIndex</emphasis> argument can - also be one of the following <computeroutput>LvItem</computeroutput> constants. If this argument is omitted, the - default is IMAGENONE: + For any item there is only 1 image index, so the index must be the same in both the large and small image lists. The + <emphasis role="italic">imageIndex</emphasis> argument can also be one of the following list-view <link + linkend="sctListViewConstantMethods">constants</link>. If this argument is omitted, the default is IMAGENONE: </para> <para> <simplelist type='vert' columns='3'> @@ -8919,6 +9022,11 @@ <varlistentry><term>itemData[optional]</term> <listitem> <para> + An item data value for this item. The list-view control allows the programmer to <link + linkend="mthSetItemDataClsListView">assign</link> an item data value to any, or all, list-view items. The item data + value can be any Rexx object. + </para> + <para> The <emphasis role="italic">itemData</emphasis> argument sets the <xref linkend="atrItemDataClsLvi"/> attribute of this list-view item. </para> @@ -8933,7 +9041,7 @@ <emphasis role="italic">mask</emphasis> attribute. However, if this object is going to be used to retrieve information about the underlying list-view item, the ooDialog framwork has no way to know what attributes the programmer wishes to retrieve. For this use of the <computeroutput>LvItem</computeroutput> object, the programmer should set the mask to the - value she wants. + value that will retrieve the information she wants. </para> <para> The <emphasis role="italic">msk</emphasis> argument can have zero or more of the following keywords, case is not @@ -8941,29 +9049,84 @@ </para> <para> <simplelist type='vert' columns='3'> - <member></member> - <member></member> - <member></member> + <member>ALL </member> + <member>COLFMT </member> + <member>COLUMNS </member> + <member>GROUPID </member> + <member>IMAGE </member> + <member>INDENT </member> + <member>NORECOMPUTE</member> + <member>PARAM </member> + <member>STATE </member> + <member>TEXT </member> </simplelist> <variablelist> - <varlistentry><term>T1</term> + <varlistentry><term>ALL</term> <listitem> <para> - text + A convenience keyword, the same as specifying a a string with every keyword in it. </para> </listitem></varlistentry> - <varlistentry><term>T2</term> + <varlistentry><term>COLFMT</term> <listitem> <para> - text + <emphasis role="bold">Requires Windows Vista or later</emphasis>. The <xref linkend="atrColumnFormatsClsLvi"/> + attribute is valid or should be set. </para> </listitem></varlistentry> - <varlistentry><term>T3</term> + <varlistentry><term>COLUMNS</term> <listitem> <para> - text + Requires Common Control <xref linkend="ovvComctl32"/> version 6.0 or later. The <xref linkend="atrColumnsClsLvi"/> + attribute is valid or should be set. </para> </listitem></varlistentry> + <varlistentry><term>GROUPID</term> + <listitem> + <para> + Requires Common Control <xref linkend="ovvComctl32"/> version 6.0 or later. The <xref linkend="atrGroupIDClsLvi"/> + attribute is valid or should be set. + </para> + </listitem></varlistentry> + <varlistentry><term>IMAGE</term> + <listitem> + <para> + The <xref linkend="atrImageIndexClsLvi"/> attribute is valid or should be set. + </para> + </listitem></varlistentry> + <varlistentry><term>INDENT</term> + <listitem> + <para> + The <xref linkend="atrIndentClsLvi"/> attribute is valid or should be set. + </para> + </listitem></varlistentry> + <varlistentry><term>NORECOMPUTE</term> + <listitem> + <para> + Used when the <computeroutput>LvItem</computeroutput> object will be used to retrieve information through the <xref + linkend="mthGetItem"/> method. Signals the list-view control not to generate a GETDISPINFO notification to retrieve + the text. Rather, the <xref linkend="atrTextClsLvi"/> attribute will contain <emphasis + role="italic">lpStrTextCallBack</emphasis>. + </para> + </listitem></varlistentry> + <varlistentry><term>PARAM</term> + <listitem> + <para> + The <xref linkend="atrItemDataClsLvi"/> attribute is valid or should be set. + </para> + </listitem></varlistentry> + <varlistentry><term>STATE</term> + <listitem> + <para> + The <xref linkend="atrStateClsLvi"/> attribute is valid or should be set. + </para> + </listitem></varlistentry> + <varlistentry><term>TEXT</term> + <listitem> + <para> + The <xref linkend="atrTextClsLvi"/> attribute is valid or should be set. + </para> + </listitem></varlistentry> </variablelist> </para> <para> @@ -8974,14 +9137,110 @@ <varlistentry><term>itemState [optional]</term> <listitem> <para> - Sets the <xref linkend="atrImageIndexClsLvi"/> attribute of this list-view item. + A list of blank separate keywords that specify the state for the list-view item. An item's state determines its + appearance and functionality. The list can contain one or more of the following keywords: </para> + <para> + <simplelist type='vert' columns='3'> + <member>CUT </member> + <member>DROPHILITED</member> + <member>FOCUSED </member> + <member>SELECTED </member> + </simplelist> + <variablelist> + <varlistentry><term>CUT</term> + <listitem> + <para> + The list-view item is marked for a cut-and-paste operation + </para> + </listitem></varlistentry> + <varlistentry><term>DROPHILITED</term> + <listitem> + <para> + The list-view item is highlighted as a drag-and-drop target. + </para> + </listitem></varlistentry> + <varlistentry><term>FOCUSED</term> + <listitem> + <para> + The list-view item has the focus, so it is surrounded by a standard focus rectangle. Although more than one item + may be selected, only one item can have the focus. + </para> + </listitem></varlistentry> + <varlistentry><term>SELECTED</term> + <listitem> + <para> + The list-view item is selected. The appearance of a selected item depends on whether it has the focus and also on + the system colors used for selection. + </para> + </listitem></varlistentry> + </variablelist> + </para> + <para> + Sets the <xref linkend="atrItemStateClsLvi"/> attribute of this list-view item. + </para> </listitem></varlistentry> <varlistentry><term>itemStateMsk [optional]</term> <listitem> <para> - Sets the <xref linkend="atrImageIndexClsLvi"/> attribute of this list-view ... [truncated message content] |
From: <mie...@us...> - 2012-12-12 23:58:03
|
Revision: 8685 http://sourceforge.net/p/oorexx/code-0/8685 Author: miesfeld Date: 2012-12-12 23:57:59 +0000 (Wed, 12 Dec 2012) Log Message: ----------- ooDialog doc, continue incremental update Modified Paths: -------------- docs/trunk/oodialog/en-US/listview.xml docs/trunk/oodialog/en-US/overview.xml Modified: docs/trunk/oodialog/en-US/listview.xml =================================================================== --- docs/trunk/oodialog/en-US/listview.xml 2012-12-12 04:18:10 UTC (rev 8684) +++ docs/trunk/oodialog/en-US/listview.xml 2012-12-12 23:57:59 UTC (rev 8685) @@ -7538,6 +7538,17 @@ <programlisting> <![CDATA[ +::method initDialog + expose list + ... + + list = self~newListView(IDC_LV_CONTACTS) + items = self~createRows + + do r over items + list~addFullRow(r) + end + ::method createRows private ... @@ -8920,15 +8931,15 @@ </row> <row> <entry><xref linkend="atrOverlayImageIndexClsLvi"/></entry> -<entry></entry> +<entry>Reflects the one-based index of the overlay image for this item.</entry> </row> <row> <entry><xref linkend="atrStateImageIndexClsLvi"/></entry> -<entry></entry> +<entry>Reflects the one-based index of the state image for this item.</entry> </row> <row> <entry><xref linkend="atrTextClsLvi"/></entry> -<entry></entry> +<entry>Reflects the text, the label, for this item.</entry> </row> </tbody></tgroup> </table> @@ -10221,26 +10232,40 @@ </programlisting> <para> - xx + Reflects the one-based index of the overlay image for this item. </para> <variablelist> <varlistentry><term><emphasis role="bold">overlayImageIndex get:</emphasis></term> <listitem> <para> - details about get + Returns the one-based index of the overlay image for this item. 0 indicates the item has no overlay image. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">overlayImageIndex set:</emphasis></term> <listitem> <para> - details about set + To specify an overlay image for this item assign the one-based index of the overlay image in the image list. Assign 0 to + indicate the item should not use an overlay image. Valid indexes are 0 through 15. This is a limitation imposed by the + operating system. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + Both the full-sized icon image list and the small icon image list can have overlay images. The overlay image is + superimposed over the item's icon image. If the overlay index is zero, the item has no overlay image. </para> + <para> + The overlay image index is actually part of the state value for an item in the underlying list-view control. The ooDialog + framework hides some of the complexity of separating the overlay index from the state value by making the index a + separate attribute in the <computeroutput>LvItem</computeroutput> object. If the programmer wants to retrieve the overlay + index only, it is necessary to set the STATE flag in the <xref linkend="atrMaskClsLiv"/> attribute. + </para> + <para> + Currently, ooDialog does not have support for overlay images in the <xref linkend="clsImageList"/> class. However, it is + anticipated that support may be added in a future enhancement. Support for overlay image indexes in the + <computeroutput>LvItem</computeroutput> class is a first step towards implementing support for overlay images. + </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> <listitem> @@ -10248,18 +10273,6 @@ Raises syntax errors when incorrect usage is detected. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> - <listitem> - <para> - This example ... -<programlisting> -<![CDATA[ - - -]]> -</programlisting> - </para> - </listitem></varlistentry> </variablelist> </section> <!-- End LvItem::overlayImageIndex() [attribute] --> @@ -10276,26 +10289,41 @@ </programlisting> <para> - xx + Reflects the one-based index of the state image for this item. </para> <variablelist> <varlistentry><term><emphasis role="bold">stateImageIndex get:</emphasis></term> <listitem> <para> - details about get + Returns the one-based index of the state image for this item. 0 indicates the item has no state image. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">stateImageIndex set:</emphasis></term> <listitem> <para> - details about set + To specify a state image for this item assign the one-based index of the state image in the state image list. Assign 0 to + indicate the item should not use an state image. Valid indexes are 0 through 15. This is a limitation imposed by the + operating system. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + The state image is displayed next to an item's icon to indicate an application-defined state. If the state image index is + zero, the item has no state image. </para> + <para> + The state image index is actually part of the state value for an item in the underlying list-view control. The ooDialog + framework hides some of the complexity of separating the state index from the state value by making the index a + separate attribute in the <computeroutput>LvItem</computeroutput> object. If the programmer wants to retrieve the state + image index only, it is necessary to set the STATE flag in the <xref linkend="atrMaskClsLiv"/> attribute. + </para> + <para> + Currently, ooDialog does not have support for setting the state image list in the <xref + linkend="mthSetImageListClsListView"/> method of the <computeroutput>ListView</computeroutput> class. However, it is + anticipated that support may be added in a future enhancement. Support for state image indexes in the + <computeroutput>LvItem</computeroutput> class is a first step towards implementing support for state images. + </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> <listitem> @@ -10303,18 +10331,6 @@ Raises syntax errors when incorrect usage is detected. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> - <listitem> - <para> - This example ... -<programlisting> -<![CDATA[ - - -]]> -</programlisting> - </para> - </listitem></varlistentry> </variablelist> </section> <!-- End LvItem::stateImageIndex() [attribute] --> @@ -10331,25 +10347,34 @@ </programlisting> <para> - xx + Reflects the text, the label, for this item. </para> <variablelist> <varlistentry><term><emphasis role="bold">text get:</emphasis></term> <listitem> <para> - details about get + Returns the text for this item. If no text has been set for this item, the <computeroutput>.nil</computeroutput> object + is returned. Note that setting the text to the empty string is different than not having the text set at all. In + addition, the operarating system uses a special value to indicate to the list-view that it should generate a GETDISPINFO + notification to retrieve the text for the item from the application. If this value is set, the string <emphasis + role="italic">lpStrTextCallBack</emphasis> is returned as the text for this item. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">text set:</emphasis></term> <listitem> <para> - details about set + Assign a string to this attribute to set the text for the item. The string must be less than or equal to 260 characters + in length. In addition the special string, <emphasis role="italic">lpStrTextCallBack</emphasis>, can be used to set the + text value for the item to the value that indicates the list-view should generate a GETDISPINFO notification. Case is not + significant when using <emphasis role="italic">lpStrTextCallBack</emphasis>. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + Currently, there is no support for the GETDISPINFO event notification in <xref linkend="mthConnectListViewEvent"/> + method. It is anticipated that support for this event will be added in the future. Until then, using the <emphasis + role="italic">lpStrTextCallBack</emphasis> value will simply result in the item appearing with no text. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> @@ -10361,11 +10386,26 @@ <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example gets the current text for an item, appends a string to the text, and sets the text for the item to the new + value: <programlisting> <![CDATA[ +::method addQualifier private + expose list + use strict arg itemIndex, additionalText + lvItem = .LvItem~new(itemIndex, , , , 'TEXT') + if list~getItem(lvItem) then do + lvItem~text = lvItem~text additionalText + + list~modifyItem(lvItem) + return .true + end + else do + return .false + end + ]]> </programlisting> </para> @@ -10481,6 +10521,9 @@ ]]> </programlisting> + The reason that the default here is false is that with very large lists, the time to fix up the full row objects can be + noticeable, .5 to 1.5 seconds for lists with over 10,000 items. Because of this, the programmer may not want the fix up + to happen during the insertion or deletion of a column. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Manual update</emphasis></term> @@ -10536,27 +10579,27 @@ </row> <row> <entry><xref linkend="mthAddSubItem"/></entry> -<entry>xx</entry> +<entry>Adds a subitem to this full row. Subitems are always added as the last subitem in the row.</entry> </row> <row> <entry><xref linkend="mthInsertSubItem"/></entry> -<entry>xx</entry> +<entry>Inserts a new subitem into this full row and adjusts the subitem indexes for all existing subitems, when needed.</entry> </row> <row> <entry><xref linkend="mthItem"/></entry> -<entry>xx</entry> +<entry>Returns the <xref linkend="clsLvItem"/> object of this full row.</entry> </row> <row> <entry><xref linkend="mthRemoveSubItem"/></entry> -<entry>xx</entry> +<entry>Removes the specified subitem from this full row.</entry> </row> <row> <entry><xref linkend="mthSubItem"/></entry> -<entry>xx</entry> +<entry>Returns the subitem specified by <emphasis role="italic">index</emphasis> of this full row, or the <computeroutput>.nil</computeroutput> object if the subitem <emphasis role="italic">index</emphasis> is not valid.</entry> </row> <row> <entry><xref linkend="mthSubItems"/></entry> -<entry>xx</entry> +<entry>Returns the count of subitems in this full row.</entry> </row> </tbody></tgroup> </table> @@ -10583,6 +10626,7 @@ <listitem> <para> The arguments are: + </para> <variablelist> <varlistentry><term>item [required]</term> <listitem> @@ -10607,7 +10651,6 @@ </para> </listitem></varlistentry> </variablelist> - </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> @@ -10703,24 +10746,23 @@ <indexterm><primary>LvFullRow class</primary><secondary>addSubItem</secondary></indexterm> <programlisting> <![CDATA[ ->>--addSubItem(--+--------+--)--------------------------------------------->< - +--type--+ +>>--addSubItem(--subitem--)---------------------->< ]]> </programlisting> <para> - xx + Adds a subitem to this full row. Subitems are always added as the last subitem in the row. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The arguments are: + The single argument is: <variablelist> - <varlistentry><term>TERM</term> + <varlistentry><term>subitem [required]</term> <listitem> <para> - xx + A <xref linkend="clsLvSubItem"/> object that specifies the subitem being added. </para> </listitem></varlistentry> </variablelist> @@ -10729,13 +10771,17 @@ <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns the index of the added subitem on success, or 0 on error. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + The <emphasis role="italic">addSubItem</emphasis> method allows the programmer to add subitems to the full row after the + <computeroutput>LvFullRow</computeroutput> object has been instantiated. Typically, all subitems would be added to the + full row at the time of instantiation through the <xref linkend="mthNewClsLvFullRow"/> method. In addition to the + <emphasis role="italic">addSubItem</emphasis> method, the <xref linkend="mthInsertSubItem"/> method can be used to insert + a subitem into the middle of the subitem list. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> @@ -10743,21 +10789,7 @@ <para> Raises syntax errors when incorrect usage is detected. </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> - <listitem> - <para> - This example ... -<programlisting> -<![CDATA[ - -]]> -</programlisting> - </para> - </listitem></varlistentry> </variablelist> </section> <!-- End LvFullRow::addSubItem() --> @@ -10766,13 +10798,12 @@ <indexterm><primary>ListView class</primary><secondary>insertSubItem</secondary></indexterm> <programlisting> <![CDATA[ ->>--insertSubItem(--+--------+--)--------------------------------------------->< - +--type--+ +>>--insertSubItem(--subItem--,--colIndex--)------>< ]]> </programlisting> <para> - xx + Inserts a new subitem into this full row and adjusts the subitem indexes for all existing subitems, when needed. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -10781,42 +10812,65 @@ The arguments are: </para> <variablelist> - <varlistentry><term>TERM</term> + <varlistentry><term>subitem [required]</term> <listitem> <para> - xx + A <xref linkend="clsLvSubItem"/> object that specifies the subitem being inserted. </para> </listitem></varlistentry> + <varlistentry><term>colIndex [required]</term> + <listitem> + <para> + The one-based index that specifies which column the subitem is inserted at. The index can not be 0 and can not be + greater than the current count of subitems + 1. That is, a subitem can not be inserted in a way that leaves the + subitems non-contiguous. + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns true on success, false on error. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + The <emphasis role="italic">insertSubItem</emphasis> method allows the programmer to add subitems to the full row after + the <computeroutput>LvFullRow</computeroutput> object has been instantiated. Typically, all subitems would be added to + the full row at the time of instantiation through the <xref linkend="mthNewClsLvFullRow"/> method. In addition to the + <emphasis role="italic">insertSubItem</emphasis> method, the <xref linkend="mthAddSubItem"/> method can be used to add a + subitem to the end of the subitem list. </para> + <para> + Inserting a new column into the middle of the exsiting subitems, will of course make the subitem index in the subitems + following the newly inserted subitem invalid. The ooDialog framework will automatically fix the subitem indexes where + needed. In addition, both the <xref linkend="atrItemClsLvSi"/> and <xref linkend="atrSubItemClsLvSi"/> attributes in the + newly inserted <emphasis role="italic">subitem</emphasis> object are set to the collect values automatically. Because of + this, the <emphasis role="italic">subitem</emphasis> object argument does not necessarily have to have correct item and + subitem index values. + </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> <listitem> <para> Raises syntax errors when incorrect usage is detected. </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example inserts a new subitem for column 3. Notice that when instantiating the + <computeroutput>LvSubItem</computeroutput> object, the code does not bother with setting the <emphasis + role="italic">item</emphasis> and <emphasis role="italic">subitem</emphasis> correctly. Rather it relies on the <emphasis + role="italic">insertSubItem</emphasis> method to set them correctly: <programlisting> <![CDATA[ + lvSubItem = .LvSubItem~new(1, 1, 'Apartment #13', 2) + lvFull~insertSubItem(lvSubItem, 3) + ]]> </programlisting> </para> @@ -10830,33 +10884,25 @@ <indexterm><primary>LvFullRow class</primary><secondary>item</secondary></indexterm> <programlisting> <![CDATA[ ->>--item(--+--------+--)--------------------------------------------->< - +--type--+ +>>--item----------------------------------------->< ]]> </programlisting> <para> - xx + Returns the <xref linkend="clsLvItem"/> object of this full row. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The arguments are: - <variablelist> - <varlistentry><term>TERM</term> - <listitem> - <para> - xx - </para> - </listitem></varlistentry> - </variablelist> + There are no arguments for this method. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns the <emphasis role="italic">LvItem</emphasis> object for this full row. All full rows must have an item object so + there is no way for this method to fail. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> @@ -10865,22 +10911,36 @@ Additional comments. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details</emphasis></term> - <listitem> - <para> - Raises syntax errors when incorrect usage is detected. - </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> - </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example gets the <computeroutput>LvFullRow</computeroutput> for the item at index 5 of the list-view. It then gets + the <computeroutput>LvItem</computeroutput> object and prints its information out to the display <programlisting> <![CDATA[ + lvfull = list~getFullRow(5) + lvitem = lvFull~item + self~printItem(lvitem) + +/* Output might be for example: + +Item columnFormats: an Array +Item columns: an Array +Item columns count: 0 +Item groupID: -2 +Item imageIndex: 3 +Item indent: 0 +Item index: 5 +Item itemData: a LvFullRow +Item itemState: FOCUSED SELECTED +Item itemStateMask: +Item mask: GROUPID IMAGE PARAM TEXT +Item overlayImageIndex: 0 +Item stateImageIndex: 0 +Item text: Clerk + +*/ ]]> </programlisting> </para> @@ -10893,13 +10953,12 @@ <indexterm><primary>LvFullRow class</primary><secondary>removeSubItem</secondary></indexterm> <programlisting> <![CDATA[ ->>--removeSubItem(--+--------+--)--------------------------------------------->< - +--type--+ +>>--removeSubItem(--index--)--------------------->< ]]> </programlisting> <para> - xx + Removes the specified subitem from this full row. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -10907,10 +10966,12 @@ <para> The arguments are: <variablelist> - <varlistentry><term>TERM</term> + <varlistentry><term>index [required]</term> <listitem> <para> - xx + The index of the subitem to remove. This is the same as the column index for the subitem. <emphasis + role="italic">index</emphasis> must be a valid, existing, subitem index. This means it can not be 0, or greater than + the count of current subitems. </para> </listitem></varlistentry> </variablelist> @@ -10919,35 +10980,28 @@ <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns the removed <computeroutput>LvSubItem</computeroutput> object on success, or the + <computeroutput>.nil</computeroutput> object on error. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + The <emphasis role="italic">removeSubItem</emphasis> method allows the programmer to remove subitem from the full row + after the <computeroutput>LvFullRow</computeroutput> object has been instantiated. Typically, all subitems would be set + correctly in the full row at the time of instantiation through the <xref linkend="mthNewClsLvFullRow"/> method. </para> + <para> + Removing a column from the middle of the exsiting subitems, will of course make the subitem index in the subitems + following the removed subitem invalid. The ooDialog framework will automatically fix the subitem indexes where needed. + </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> <listitem> <para> Raises syntax errors when incorrect usage is detected. </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> - <listitem> - <para> - This example ... -<programlisting> -<![CDATA[ - -]]> -</programlisting> - </para> - </listitem></varlistentry> </variablelist> </section> <!-- End LvFullRow::removeSubItem() --> @@ -10956,24 +11010,24 @@ <indexterm><primary>LvFullRow class</primary><secondary>subItem</secondary></indexterm> <programlisting> <![CDATA[ ->>--subItem(--+--------+--)--------------------------------------------->< - +--type--+ +>>--subItem(--index--)--------------------------->< ]]> </programlisting> <para> - xx + Returns the subitem specified by <emphasis role="italic">index</emphasis> of this full row, or the + <computeroutput>.nil</computeroutput> object if the subitem <emphasis role="italic">index</emphasis> is not valid. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The arguments are: + The single argument is: <variablelist> - <varlistentry><term>TERM</term> + <varlistentry><term>index [required]</term> <listitem> <para> - xx + The one-based index of the subitem requested. </para> </listitem></varlistentry> </variablelist> @@ -10982,31 +11036,31 @@ <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns the requested <xref linkend="clsLvSubItem"/> object on success, or the <computeroutput>.nil</computeroutput> + object on error. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> - <listitem> - <para> - Additional comments. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details</emphasis></term> - <listitem> - <para> - Raises syntax errors when incorrect usage is detected. - </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> - </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example gets the subitem in column 3 of the item at index 4 in the list-view and prints out its information: <programlisting> <![CDATA[ + + lvfull = list~getFullRow(4) + subItem = lvFull~subItem(3) + self~printSubItem(subItem) + +/* Output might be: + +Subitem imageIndex: 11 +Subitem item: 4 +Subitem mask: IMAGE TEXT +Subitem subitem: 3 +Subitem text: ca...@sh... + +*/ ]]> </programlisting> </para> @@ -11019,50 +11073,26 @@ <indexterm><primary>LvFullRow class</primary><secondary>subItems</secondary></indexterm> <programlisting> <![CDATA[ ->>--subItems(--+--------+--)--------------------------------------------->< - +--type--+ +>>--subItems------------------------------------->< ]]> </programlisting> <para> - xx + Returns the count of subitems in this full row. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The arguments are: - <variablelist> - <varlistentry><term>TERM</term> - <listitem> - <para> - xx - </para> - </listitem></varlistentry> - </variablelist> + There are no arguments for this method. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns the count of subitems in this full row. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> - <listitem> - <para> - Additional comments. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details</emphasis></term> - <listitem> - <para> - Raises syntax errors when incorrect usage is detected. - </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> - </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> @@ -11070,6 +11100,38 @@ <programlisting> <![CDATA[ + lvfull = list~getFullRow(4) + if lvfull~subitems == 0 then do + say 'No subitems for row at index 4' + return + end + + do i = 1 to lvfull~subitems + subItem = lvFull~subItem(i) + self~printSubItem(subItem) + end + +/* Output might be: + +Item imageIndex: 13 +Item item: 4 +Item mask: IMAGE TEXT +Item subitem: 1 +Item text: Cienna + +Item imageIndex: 18 +Item item: 4 +Item mask: IMAGE TEXT +Item subitem: 2 +Item text: Acer + +Item imageIndex: 11 +Item item: 4 +Item mask: IMAGE TEXT +Item subitem: 3 +Item text: ca...@sh... + +*/ ]]> </programlisting> </para> @@ -11083,11 +11145,27 @@ <section id="clsLvSubItem" xreflabel="LvSubItem"><title>LvSubItem Class</title> <indexterm><primary>LvSubItem class</primary></indexterm> <para> - A LvSubItem object ... + A LvSubItem object represents a specific subitem of a single item within a list-view control. Each item in a list-view can + have one or more subitems. Each subitem can have a text string and an icon. In report view, the text, and optionally the + icon, is displayed in a column separate from the item's icon and label. To display the subitem's icon, the list-view must + have the SUBITEMIMAGES <link linkend="mthAddExtendedStyle">extended</link> style. </para> <para> - xx + All items in a list-view control have the same number of subitems. The number of subitems is determined by the number of + columns in the list-view control. When a column is <link linkend="mthInsertColumnPX">added</link> to a list-view control, + its associated subitem index is specified. When a column is added to a list-view, the list-view control creates a subitem + for every existing item with a default value of no text and no icon. When a column is removed from a list-view, the + list-view deletes the information it maintains for every subitem of that column. </para> +<para> + The list-view does not have to be in report view to have subitems. It does not have to be in report view to have columns + added or deleted, the list-view can be in any view mode. +</para> +<para> + <computeroutput>LvSubItem</computeroutput> objects can be used to set the information for a subitem or to receive + information concerning a subitem. In addition, <xref linkend="clsLvFullRow"/> objects can be composed of subitem objects in + addition to a <xref linkend="clsLvItem"/> object. +</para> <section id="sctMethodsLvSubItem"><title>Method Table</title> <para> @@ -11109,13 +11187,33 @@ <entry align="center"><emphasis role="bold">Class Methods</emphasis></entry> </row> <row> -<entry>new</entry> <entry><link linkend="mthNewClsLvSubItem">new</link></entry> +<entry>Instantiates a new <computeroutput>LvSubItem</computeroutput> object.</entry> </row> <row> -<entry align="center"><emphasis role="bold">Instance Methods</emphasis></entry> -<entry align="center"><emphasis role="bold">Instance Methods</emphasis></entry> +<entry align="center"><emphasis role="bold">Attribute Methods</emphasis></entry> +<entry align="center"><emphasis role="bold">Attribute Methods</emphasis></entry> </row> +<row> +<entry><xref linkend="atrImageIndexClsLvSi"/></entry> +<entry>Reflects the index in the smalll icon <link linkend="mthSetImageListClsListView">image</link> list for this subitem.</entry> +</row> +<row> +<entry><xref linkend="atrItemClsLvSi"/></entry> +<entry>Reflects the index of the item in the list-view that this subitem belongs to.</entry> +</row> +<row> +<entry><xref linkend="atrMaskClsLvSi"/></entry> +<entry>The <emphasis role="italic">mask</emphasis> attribute is used to specify which values of the <computeroutput>LvSubItem</computeroutput> object are valid to set or recieve the information for a list-view item's subitem.</entry> +</row> +<row> +<entry><xref linkend="atrSubItemClsLvSi"/></entry> +<entry>Reflects the subitem index of this <computeroutput>LvSubItem</computeroutput> object.</entry> +</row> +<row> +<entry><xref linkend="atrTextClsLvSi"/></entry> +<entry>Reflects the text, the label, for this subitem.</entry> +</row> </tbody></tgroup> </table> </para> @@ -11126,33 +11224,156 @@ <indexterm><primary>LvSubItem class</primary><secondary>new</secondary></indexterm> <programlisting> <![CDATA[ ->>--new(--+--------+--)--------------------------------------------->< - +--type--+ +>>--new(--item-,-subItem--+---------+--+--------------+--+--------+--)--------->< + +-,-text--+ +-,-imageIndex-+ +-,-mask-+ ]]> </programlisting> <para> - xx + Instantiates a new <computeroutput>LvSubItem</computeroutput> object with the parameters specified. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - xx + Instantiates a new <computeroutput>LvSubItem</computeroutput> object. + </para> <variablelist> - <varlistentry><term>TERM</term> + <varlistentry><term>item [required]</term> <listitem> <para> - xx + The zero-based index of the item this subitem belongs to. The argument can not be less than 0. The <emphasis + role="italic">item</emphasis> argument sets the <xref linkend="atrItemClsLvSi"/> attribute of this subitem. </para> + <para> + Note that depending on the use of this subitem, the ooDialog framework may modify the index attribute. For + instance if the <computeroutput>LvSubItem</computeroutput> is contained in a <xref linkend="clsLvFullRow"/> object and + the row is added to a list-view, the ooDialog framework will adjust the <emphasis role="italic">index</emphasis> + attribute to reflect the actual index of the added item. + </para> </listitem></varlistentry> + <varlistentry><term>subItem [required]</term> + <listitem> + <para> + The one-based index of this subitem. The argument can not be less than 1. The <emphasis role="italic">suItem</emphasis> + argument sets the <xref linkend="atrSubItemClsLvSi"/> attribute of this subitem. + </para> + <para> + Note that depending on the use of this subitem, the ooDialog framework may modify the <emphasis + role="italic">subItem</emphasis> attribute. For instance if the <computeroutput>LvSubItem</computeroutput> is placed + into a <xref linkend="clsLvFullRow"/> object, the ooDialog framework will adjust + the <emphasis role="italic">subItem</emphasis> attribute to reflect the actual index of the column of the subitem in + the full row. + </para> + </listitem></varlistentry> + <varlistentry><term>text [optional]</term> + <listitem> + <para> + Sets the text, or label, for this list-view subitem. The <emphasis role="italic">text</emphasis> argument sets the + <xref linkend="atrTextClsLvSi"/> attribute of this list-view subitem. + </para> + </listitem></varlistentry> + <varlistentry><term>imageIndex [optional]</term> + <listitem> + <para> + The zero-based index of the subitem's icon in the control's small icon <link + linkend="mthSetImageListClsListView">image</link> list. Note that the image index has no meaning if the list-view does + not have the SUBITEMIMAGES <link linkend="mthAddExtendedStyle">extended</link> style. + </para> + <para> + The <emphasis role="italic">imageIndex</emphasis> argument can also be one of the following list-view <link + linkend="sctListViewConstantMethods">constants</link>. If this argument is omitted, the default is IMAGENONE: + </para> + <para> + <simplelist type='vert' columns='3'> + <member>IMAGECALLBACK</member> + <member>IMAGENONE </member> + </simplelist> + <variablelist> + <varlistentry><term>IMAGECALLBACK</term> + <listitem> + <para> + Indicates the list-view control should send the GETDISPINFO notification message to retrieve the icon index for the + subitem. + </para> + </listitem></varlistentry> + <varlistentry><term>IMAGENONE</term> + <listitem> + <para> + The subitem does not have an icon. This is the default if this argument omitted. + </para> + </listitem></varlistentry> + </variablelist> + </para> + <para> + The <emphasis role="italic">imageIndex</emphasis> argument sets the <xref linkend="atrImageIndexClsLvSi"/> attribute of + this subitem. + </para> + </listitem></varlistentry> + <varlistentry><term>mask [optional]</term> + <listitem> + <para> + A list of blank separate keywords that specify which attributes of this <computeroutput>LvSubItem</computeroutput> + object contain data to be set or which attributes are being requested. In general, the ooDialog framework will try to + set the <xref linkend="atrMaskClsLvSi"/> attribute correctly without the programmer having to worry about this + argument. As each attribute of the <computeroutput>LvSubItem</computeroutput> object is set, the appropriate keyword is + added to the <emphasis role="italic">mask</emphasis> attribute. However, if this object is going to be used to retrieve + information about the underlying list-view subitem, the ooDialog framwork has no way to know what attributes the + programmer wishes to retrieve. For this use of the <computeroutput>LvSubItem</computeroutput> object, the programmer + should set the mask to the value that will retrieve the information she wants. + </para> + <para> + The <emphasis role="italic">mask</emphasis> argument can have zero or more of the following keywords, case is not + significant: + </para> + <para> + <simplelist type='vert' columns='3'> + <member>ALL </member> + <member>IMAGE </member> + <member>NORECOMPUTE</member> + <member>TEXT </member> + </simplelist> + <variablelist> + <varlistentry><term>ALL</term> + <listitem> + <para> + A convenience keyword, the same as using the string: <emphasis role="italic">IMAGE NORECOMPUTE TEXT</emphasis>. + </para> + </listitem></varlistentry> + <varlistentry><term>IMAGE</term> + <listitem> + <para> + The <xref linkend="atrImageIndexClsLvSi"/> attribute is valid or should be set. + </para> + </listitem></varlistentry> + <varlistentry><term>NORECOMPUTE</term> + <listitem> + <para> + Used when the <computeroutput>LvSubItem</computeroutput> object will be used to retrieve information through the + <xref linkend="mthGetSubItem"/> method. Signals the list-view control should not generate a GETDISPINFO + notification to retrieve the text. Rather, the <xref linkend="atrTextClsLvSi"/> attribute will contain <emphasis + role="italic">lpStrTextCallBack</emphasis>. + </para> + </listitem></varlistentry> + <varlistentry><term>TEXT</term> + <listitem> + <para> + The <xref linkend="atrTextClsLvSi"/> attribute is valid or should be set. + </para> + </listitem></varlistentry> + </variablelist> + </para> + <para> + The <emphasis role="italic">mask</emphasis> argument sets the <xref linkend="atrMaskClsLvSi"/> attribute of this + subitem. + </para> + </listitem></varlistentry> </variablelist> - </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns a newly instantiated and initalized <computeroutput>LvSubItem</computeroutput> object. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> @@ -11166,17 +11387,36 @@ <para> Raises syntax errors when incorrect arguments are detected. </para> - <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. - </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example shows <computeroutput>LvSubItem</computeroutput> objects being instantiated and used in a <xref + linkend="clsLvFullRow"/> object, which in turn is used to add a new item to the list-view. Note that the list-viw has the + extended SUBITEMIMAGES style and the use of the <emphasis role="italic">imageIndex</emphasis> argument in the <emphasis + role="italic">new</emphasis> method. Each column in the list-view will have its own icon: <programlisting> <![CDATA[ +::method populateList private + use strict arg list + + list~InsertColumnPx(0, "Title", 150) + ret = list~InsertColumnPx(1, "Name", 75) + ret = list~InsertColumnPx(2, "Last", 100) + ret = list~InsertColumnPx(3, "e-mail", 150) + + list~addExtendedStyle("FULLROWSELECT UNDERLINEHOT ONECLICKACTIVATE SUBITEMIMAGES") + + lvItem = .LvItem~new(0, "Business manager", 6) + lvSub1 = .LvSubItem~new(0, 1, "Tom", 14) + lvSub2 = .LvSubItem~new(0, 2, "Sawyer", 26) + lvSub3 = .LvSubItem~new(0, 3, "ts...@go...", 11) + lvFullRow = .LvFullRow~new(lvItem, lvSub1, lvSub2, lvSub3, .true) + list~addFullRow(lvFullRow) + + ... + ]]> </programlisting> </para> @@ -11197,25 +11437,32 @@ </programlisting> <para> - xx + Reflects the index in the small icon <link linkend="mthSetImageListClsListView">image</link> list for this subitem. </para> <variablelist> <varlistentry><term><emphasis role="bold">imageIndex get:</emphasis></term> <listitem> <para> - details about get + Returns this subitem's icon image index, or one of the image <link linkend="sctListViewConstantMethods">constants</link> + supplied by the <computeroutput>ListView</computeroutput> class, IMAGENONE or IMAGECALLBACK. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">imageIndex set:</emphasis></term> <listitem> <para> - details about set + Set this attribute to the index in the small icon image list for this subitem, or to one of the image <link + linkend="sctListViewConstantMethods">constants</link> supplied by the <computeroutput>ListView</computeroutput> class, + IMAGENONE or IMAGECALLBACK. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + In general, if the programmer does not explicitly set this attribute, the ooDialog framework will set it to the IMAGENONE + constant. When the <computeroutput>LvSubItem</computeroutput> object is used to retrieve information about a subitem, the + list-view control does not update the value for the index if the list-view does not have the SUBITEMIMAGES <link + linkend="mthAddExtendedStyle">extended</link> style. Because of this, the value of this attribute is not well defined + when the list-view does not have the SUBITEMIMAGES style. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> @@ -11227,16 +11474,20 @@ <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example will set, or change, the image index for the subitem icon of the item at index 13, column 2 to 3. None of + the other list-view item information will be changed. <programlisting> <![CDATA[ + lvSubItem = .LvSubItem~new(13, 2, , 3) + list~modifyItem(lvItem) ]]> </programlisting> </para> </listitem></varlistentry> </variablelist> + </section> <!-- End LvSubItem::imageIndex() [attribute] --> <section id="atrItemClsLvSi" xreflabel="item"><title>item (Attribute)</title> @@ -11252,45 +11503,28 @@ </programlisting> <para> - xx + Reflects the index of the item in the list-view that this subitem belongs to. </para> <variablelist> - <varlistentry><term><emphasis role="bold">item get:</emphasis></term> + <varlistentry><term><emphasis role="bold">index get:</emphasis></term> <listitem> <para> - details about get + Returns the zero-based index of this subitem's item. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">item set:</emphasis></term> + <varlistentry><term><emphasis role="bold">index set:</emphasis></term> <listitem> <para> - details about set + Set this attribute to a zero-based index to specify which item in the list-view this subitem belongs to. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + If this subitem is placed into a <xref linkend="clsLvFullRow"/> object, the ooDialog framework will update this attribute + to reflect the actual item index of the full row the subitem is placed in. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details</emphasis></term> - <listitem> - <para> - Raises syntax errors when incorrect usage is detected. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> - <listitem> - <para> - This example ... -<programlisting> -<![CDATA[ - - -]]> -</programlisting> - </para> - </listitem></varlistentry> </variablelist> </section> <!-- End LvSubItem::item() [attribute] --> @@ -11307,26 +11541,83 @@ </programlisting> <para> - xx + The <emphasis role="italic">mask</emphasis> attribute is used to specify which values of the + <computeroutput>LvSubItem</computeroutput> object are valid to set or recieve the information for a list-view item's + subitem. </para> <variablelist> <varlistentry><term><emphasis role="bold">mask get:</emphasis></term> <listitem> <para> - details about get + Returns a blank separated list of keywords specifying which attributes of this subitem are valid. The possible keywords + are listed in the remarks section. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">mask set:</emphasis></term> <listitem> <para> - details about set + To specify which attributes in this item are to be used to set or recieve information, assign a list of blank separated + keywords to this attribute. The possible keywords are listed in the remarks section. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + The <emphasis role="italic">mask</emphasis> attributed contains a list of blank separate keywords that specify which + attributes of this <computeroutput>LvSubItem</computeroutput> object contain data to be set or which attributes are being + requested. In general, when setting data, the ooDialog framework will try to set the <emphasis + role="italic">mask</emphasis> attribute correctly without the programmer having to worry about this argument. As each + attribute of the <computeroutput>LvSubItem</computeroutput> object is set, the appropriate keyword is added to the + <emphasis role="italic">mask</emphasis> attribute. </para> + <para> + However, if this object is going to be used to retrieve information about the underlying list-view item's subitem, the + ooDialog framwork has no way to know what attributes the programmer wishes to retrieve. For this use of the + <computeroutput>LvSubItem</computeroutput> object, the programmer should set the mask to the value that will retrieve the + information he wants. + </para> + <para> + The <emphasis role="italic">mask</emphasis> attribute can have zero or more of the following keywords. When assigning the + string to this attribute case is insignificant. When getting the value of this attribute, the returned keywords will be + all upper-cased: + </para> + <para> + <simplelist type='vert' columns='3'> + <member>ALL </member> + <member>IMAGE </member> + <member>NORECOMPUTE</member> + <member>TEXT </member> + </simplelist> + <variablelist> + <varlistentry><term>ALL</term> + <listitem> + <para> + A convenience keyword, the same as using the string: <emphasis role="italic">IMAGE NORECOMPUTE TEXT</emphasis>. + </para> + </listitem></varlistentry> + <varlistentry><term>IMAGE</term> + <listitem> + <para> + The <xref linkend="atrImageIndexClsLvSi"/> attribute is valid or should be set. + </para> + </listitem></varlistentry> + <varlistentry><term>NORECOMPUTE</term> + <listitem> + <para> + Used when the <computeroutput>LvSubItem</computeroutput> object will be used to retrieve information through the + <xref linkend="mthGetSubItem"/> method. Signals the list-view control should not generate a GETDISPINFO + notification to retrieve the text. Rather, the <xref linkend="atrTextClsLvSi"/> attribute will contain <emphasis + role="italic">lpStrTextCallBack</emphasis>. + </para> + </listitem></varlistentry> + <varlistentry><term>TEXT</term> + <listitem> + <para> + The <xref linkend="atrTextClsLvSi"/> attribute is valid or should be set. + </para> + </listitem></varlistentry> + </variablelist> + </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> <listitem> @@ -11337,13 +11628,27 @@ <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example sets the icon index to 2, for the subitem in column 3 of the item at index 11. In this example, the mask + attribute is set explicitly to make a point. But it is not actually needed: <programlisting> <![CDATA[ + subitem = .LvSubItem~new(11, 3, , 2, "IMAGE") + list~modifySubItem(subitem) + ]]> </programlisting> + This code snippet will work exactly the same as the example above: +<programlisting> +<![CDATA[ + + subitem = .LvSubItem~new(11, 3, , 2) + + list~modifySubItem(subitem) + +]]> +</programlisting> </para> </listitem></varlistentry> </variablelist> @@ -11362,45 +11667,28 @@ </programlisting> <para> - xx + Reflects the subitem index of the <computeroutput>LvSubItem</computeroutput> object. </para> <variablelist> <varlistentry><term><emphasis role="bold">subItem get:</emphasis></term> <listitem> <para> - details about get + Returns the one-based subitem index of this object. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">subItem set:</emphasis></term> <listitem> <para> - details about set + Set this attribute to the one-based index of the list-view subitem this object represents. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + If this subitem is placed into a <xref linkend="clsLvFullRow"/> object, the ooDialog framework will update this attribute + to reflect the actual column of the full row the subitem is placed at. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details</emphasis></term> - <listitem> - <para> - Raises syntax errors when incorrect usage is detected. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> - <listitem> - <para> - This example ... -<programlisting> -<![CDATA[ - - -]]> -</programlisting> - </para> - </listitem></varlistentry> </variablelist> </section> <!-- End LvSubItem::subItem() [attribute] --> @@ -11417,25 +11705,34 @@ </programlisting> <para> - xx + Reflects the text, the label, for this subitem. </para> <variablelist> <varlistentry><term><emphasis role="bold">text get:</emphasis></term> <listitem> <para> - details about get + Returns the text for this subitem. If no text has been set for this subitem, the <computeroutput>.nil</computeroutput> + object is returned. Note that setting the text to the empty string is different than not having the text set at all. In + addition, the operarating system uses a special value to indicate to the list-view that it should generate a GETDISPINFO + notification to retrieve the text for the subitem from the application. If this value is set, the string <emphasis + role="italic">lpStrTextCallBack</emphasis> is returned as the text for this subitem. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">text set:</emphasis></term> <listitem> <para> - details about set + Assign a string to this attribute to set the text for the subitem. The string must be less than or equal to 260 + characters in length. In addition the special string, <emphasis role="italic">lpStrTextCallBack</emphasis>, can be used + to set the text value for the subitem to the value that indicates the list-view should generate a GETDISPINFO + notification. Case is not significant when using <emphasis role="italic">lpStrTextCallBack</emphasis>. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + Currently, there is no support for the GETDISPINFO event notification in <xref linkend="mthConnectListViewEvent"/> + method. It is anticipated that support for this event will be added in the future. Until then, using the <emphasis + role="italic">lpStrTextCallBack</emphasis> value will simply result in the subitem appearing with no text. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> @@ -11447,11 +11744,26 @@ <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example gets the current text for a subitem, appends a string to the text, and sets the text for the subitem to the + new value: <programlisting> <![CDATA[ +::method addQualifier private + expose list + use strict arg itemIndex, subitemIdnex, additionalText + lvSubItem = .LvSubItem~new(itemIndex, subitemIndex, , , 'TEXT') + if list~getSubItem(lvSubItem) then do + lvSubItem~text = lvSubItem~text additionalText + + list~modifySubItem(lvSubItem) + return .true + end + else do + return .false + end + ]]> </programlisting> </para> Modified: docs/trunk/oodialog/en-US/overview.xml =================================================================== --- docs/trunk/oodialog/en-US/overview.xml 2012-12-12 04:18:10 UTC (rev 8684) +++ docs/trunk/oodialog/en-US/overview.xml 2012-12-12 23:57:59 UTC (rev 8685) @@ -1363,11 +1363,18 @@ <section id="sctHistory"><title>History</title> <para> ooDialog is a Windows only extension to Open Object Rexx and appeared in the first version of IBM's Object Rexx for - Windows. Object REXX for Windows NT & 95 Interpreter Edition V1.0 was announced very early in 1997. It included - ooDialog and could run on Windows 95 and Windows NT 3.5. However, comments within the code and sections of code itself - in ooDialog, indicate that at one point ooDialog could run on Windows 3.0 and 3.1. + Windows. This section attempts to give a rough over-view of the history of ooDialog and continues with notes pertaining to + the sequential releases of ooDialog past ooDialog 4.1.2 </para> + + +<section id="sctPreHistory"><title>Prehistory Timeline</title> <para> + Object REXX for Windows NT & 95 Interpreter Edition V1.0 was announced very early in 1997. It included ooDialog and + could run on Windows 95 and Windows NT 3.5. However, comments within the code and sections of code itself in ooDialog, + indicate that at one point ooDialog could run on Windows 3.0 and 3.1. +</para> +<para> IBM announced and released several successive versions of Object Rexx for Windows over the following years. For instance, Object REXX for Windows V2R1 was announced March 2001. In May 2004, IBM announced its intention to contribute the source code for Object Rexx to RexxLA, and the ooRexx project was born. It took the best part of a year @@ -1516,13 +1523,13 @@ installation, provided the ooRexx installation meets the minimum required for the ooDialog version. </para> -</section> +</section> <!-- End Section Prehistory Timeline --> -<section id="sctCurrentRelease"><title>Current Release</title> +<section id="sct420Release"><title>ooDialog Release 4.2.0</title> <para> - The current release of ooDialog is the 4.2.0 level ooDialog. It is the first major enhancement of ooDialog in over a - decade. This ooDialog has a lot of new and different things in it. In addition to the new dialog classes, new dialog - control classes, new methods on existing classes, it includes design changes intended to simplify areas of ooDialog + ooDialog 4.2.0 was relased in late August of 2012. It was the first major enhancement of ooDialog in over a decade. This + ooDialog has a lot of new and different things in it. In addition to the new dialog classes, new dialog control classes, + new methods on existing classes, it includes design changes intended to simplify areas of ooDialog that seem to have been confusing in the past. Enhancements have been made that fix areas of ooDialog that have always been broken. All ooDialog users should take a close look at these changes. </para> @@ -2003,15 +2010,283 @@ </para> </listitem></varlistentry> </variablelist> -</section> +</section> <!-- End Section ooDialog Release 4.2.0 --> + +</section> <!-- End Section History --> + + +<section id="sctCurrentRelease"><title>Current Release</title> +<para> + The current release of ooDialog is 4.2.1. It is a 4.2.0 level ooDialog, which means it can be installed to any ooRexx + installation that is at least version 4.1.0. The following is a brief summary of the changes in ooDialog 4.2.1 from 4.2.0. +</para> + +<variablelist> + <varlistentry><term><emphasis role="bold">Bug Fixes in ooDialog 4.2.1:</emphasis></term> + <listitem> + <para> + The following bugs were fixed in this release. The bug fix numbers can be used to look up details concerning the bug on + SourceForge + </para> + <itemizedlist> + <listitem> + <para> + * #1116 Debug print outs left in ooDialog 4.2.0 + </para> + </listitem> + <listitem> + <para> + * #1117 Method handler passed wrong argument for TreeView EXPANDING event + </para> + </listitem> + <listitem> + <para> + * #1121 ooDialog appcrash running forward class(super) continue + </para> + </listitem> + <listitem> + <para> + * #1124 ooDialog - failed to locate .h file message incorrect + </para> + </listitem> + <listitem> + <para> + * #1126 ooDialog - args sent to the HELP event handler incorrect + </para> + </listitem> + <listitem> + <para> + * #1128 ooDialog UtilityClasses.cls: typo + </para> + </listitem> + <listitem> + <para> + * #1138 MessageDialog: Failure in system service + </para> + </listitem> + <listitem> + <para> + * #1141 ooDialog - connecting system menu command events can fail + </para> + </listitem> + <listitem> + <para> + * #1145 TimedMessage dialog remains on screen after ok() method is invoked + </para> + </listitem> + <listitem> + <para> + * #1146 Return code from ListView::deleteColumn() not as documented + </para> + </listitem> + <listitem> + <para> + * #1147 SingleSelection class + </para> + </listitem> + <listitem> + <para> + * #1149 Potential crash in ooDialog connectKeyPress() method + </para> + </listitem> + </itemizedlist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Feature Requests Added to ooDialog 4.2.1:</emphasis></term> + <listitem> + <para> + The following Request for Feature Ehancements were implemented in the release. Details concerning the enhancements can be + looked up on SourceForge using the listed tracker item numbers. + </para> + <itemizedlist> + <listitem> + <para> + * #42 OODialog List Control Class (report) format individual lines + </para> + </listitem> + <listitem> + <para> + * #130 OODialog List Control Class Activate sort headers + </para> + </listitem> + <listitem> + <para> + * #419 Add Tooltip control + </para> + </listitem> + <listitem> + <para> + * #420 Would like to have an AddButtonStem method. + </para> + </listitem> + <listitem> + <para> + * #483 ooDialog setColor and dialog background improvements + </para> + </listitem> + <listitem> + <para> + * #484 ooDialog setColor methods should not be restricted to the 19 palette indexes + </para> + </listitem> + <listitem> + <para> + * #485 Treeview itemData + </para> + </listitem> + <listitem> + <para> + * #486 ooDialog - the TreeView Expanding event should allow a veto + </para> + </listitem> + <listitem> + <para> + * #487 ooDialog - It ... [truncated message content] |
From: <mie...@us...> - 2012-12-14 01:26:51
|
Revision: 8699 http://sourceforge.net/p/oorexx/code-0/8699 Author: miesfeld Date: 2012-12-14 01:26:48 +0000 (Fri, 14 Dec 2012) Log Message: ----------- ooDialog - Bump doc in trunk to 4.2.2 Modified Paths: -------------- docs/trunk/oodialog/en-US/oodialog.ent docs/trunk/oodialog/en-US/overview.xml Modified: docs/trunk/oodialog/en-US/oodialog.ent =================================================================== --- docs/trunk/oodialog/en-US/oodialog.ent 2012-12-14 01:26:01 UTC (rev 8698) +++ docs/trunk/oodialog/en-US/oodialog.ent 2012-12-14 01:26:48 UTC (rev 8699) @@ -2,5 +2,5 @@ <!ENTITY BOOKID "oodialog"> <!ENTITY YEAR "2005-2012"> <!ENTITY HOLDER "Rexx Language Association. All rights reserved."> -<!ENTITY VERSION "4.2.1"> +<!ENTITY VERSION "4.2.2"> <!ENTITY EDITION "1"> Modified: docs/trunk/oodialog/en-US/overview.xml =================================================================== --- docs/trunk/oodialog/en-US/overview.xml 2012-12-14 01:26:01 UTC (rev 8698) +++ docs/trunk/oodialog/en-US/overview.xml 2012-12-14 01:26:48 UTC (rev 8699) @@ -2013,13 +2013,10 @@ </section> <!-- End Section ooDialog Release 4.2.0 --> -</section> <!-- End Section History --> - - -<section id="sctCurrentRelease"><title>Current Release</title> +<section id="sct421Release"><title>ooDialog Release 4.2.1</title> <para> - The current release of ooDialog is 4.2.1. It is a 4.2.0 level ooDialog, which means it can be installed to any ooRexx - installation that is at least version 4.1.0. The following is a brief summary of the changes in ooDialog 4.2.1 from 4.2.0. + ooDialog 4.2.1 was released in ... It is a 4.2.0 level ooDialog, which means it can be installed to any ooRexx installation + that is at least version 4.1.0. The following is a brief summary of the changes in ooDialog 4.2.1 from ooDialog 4.2.0. </para> <variablelist> @@ -2213,49 +2210,226 @@ <varlistentry><term><emphasis role="bold">New ListView support classes in ooDialog 4.2.1:</emphasis></term> <listitem> <para> - xxx and xxx sss. + <xref linkend="clsLvItem"/> class: Represents a single list-view item. The attributes of the LvItem are the attributes + of the underlying Windows list-view item. </para> + <para> + <xref linkend="clsLvSubItem"/> class: Represents a single list-view subitem. The attributes of the LvSubItem are the + attributes of the underlying Windows list-view subitem. + </para> + <para> + <xref linkend="clsLvFullRow"/> class: List-view items can contain subitems. This is most apparent in the row view of a + list-view where the subitems are displayed in columns next to the item. However, the subitems, once added to an item, + are always present, even if the list-view is in another view, such as icon view. + </para> + <para> + The LvFullRow class represents the list-view item and all its subitems. LvFullRow objects can be used to insert an item + and all data associated with the item into a list-view at one time. + </para> + <para> + <xref linkend="clsLvCustomDrawSimple"/> class: The LvCustomDrawSimple class is used in conjuction with the custom draw + facility for ListView controls. + </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">New dialog classes in ooDialog 4.2.1:</emphasis></term> <listitem> <para> - xxx and xxx sss. + <xref linkend="clsCustomDraw"/> class: The CustomDraw class is a new mixin class. Dialogs in ooDialog can inherit this + class, which then gives the dialog the ability to access the custom draw facility. </para> + <para> + The ListView and TreeView controls can register for custom draw. + </para> </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">New dialog control classes in ooDialog 4.2.1:</emphasis></term> + <listitem> + <para> + <xref linkend="clsToolTip"/> class: Tooltip controls are pop-up windows that display text. Typically the text describes + a <emphasis role="italic">tool</emphasis>. A <emphasis role="italic">tool</emphasis> is either a window or an + application defined area within a window. + </para> <varlistentry><term><emphasis role="bold">New utility classes in ooDialog 4.2.1:</emphasis></term> <listitem> <para> - xxx and xxx sss. + <xref linkend="clsTvCustomDrawSimple"/> class: The TvCustomDrawSimple class is used in conjuction with the custom draw + facility for TreeView controls. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">New Methods in ooDialog 4.2.1:</emphasis></term> <listitem> + <variablelist> + <varlistentry><term><emphasis role="bold">In the PlainBaseDialog class:</emphasis></term> + <listitem> + <para> + <xref linkend="mthGetTextSizeTitleBar"/> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">In the DialogControl class:</emphasis></term> + <listitem> + <para> + <xref linkend="mthUseVersion"/>. + </para> + <para> + <xref linkend="mthUsingVersion"/>. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">In the ListView class:</emphasis></term> + <listitem> + <para> + <xref linkend="mthAddFullRow"/> + </para> + <para> + <xref linkend="mthInsertFullRow"/> + </para> + <para> + <xref linkend="mthPrependFullRow"/> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">In the TreeView class:</emphasis></term> + <listitem> + <para> + <xref linkend="mthFind"/> + </para> + <para> + <xref linkend="mthGetItemDataClsTreeView"/> + </para> + <para> + <xref linkend="mthItemTextClsTreeView"/> + </para> <para> - xxx and xxx sss. + <xref linkend="mthRemoveItemDataClsTreeView"/> + </para> + <para> + <xref linkend="mthSetItemDataClsTreeView"/> </para> </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> <varlistentry><term><emphasis role="bold">New Attributes in ooDialog 4.2.1:</emphasis></term> <listitem> + <variablelist> + <varlistentry><term><emphasis role="bold">In the SM (system metrics) class:</emphasis></term> + <listitem> + <para> + <xref linkend="atrCxSize"/> + </para> <para> - xxx and xxx sss. + <xref linkend="atrCxSmIcon"/>. + </para> + <para> + <xref linkend="atrCyMenu"/>. </para> </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Enhanced Methods in ooDialog 4.2.1:</emphasis></term> <listitem> + <variablelist> + <varlistentry><term><emphasis role="bold">In the DialogControl class:</emphasis></term> + <listitem> + <para> + <xref linkend="mthSetColor"/> + </para> + <para> + <xref linkend="mthSetSysColor"/> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">In the DialogExtensions class:</emphasis></term> + <listitem> + <para> + <xref linkend="mthSetControlColor"/>. + </para> + <para> + <xref linkend="mthSetControlSysColor"/>. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">In the TreeView class:</emphasis></term> + <listitem> + <para> + <xref linkend="mthInsertClsTreeView"/> + </para> + <para> + <xref linkend="mthItemInfoClsTreeView"/> + </para> + <para> + <xref linkend="mthModifyClsTreeView"/> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">In the EventNotification class:</emphasis></term> + <listitem> + <para> + <xref linkend="mthConnectListViewEvent"/> + </para> + <itemizedlist> + <listitem> + <para> + the KEYDOWNEX event is added. + </para> + </listitem> + <listitem> + <para> + the BEGINEDIT event is enhanced + </para> + </listitem> + <listitem> + <para> + the ENDEDIT event is enhanced + </para> + </listitem> + </itemizedlist> + <para> + <xref linkend="mthConnectTreeViewEvent"/> + </para> + <itemizedlist> + <listitem> + <para> + the KEYDOWNEX event is added. + </para> + </listitem> + <listitem> + <para> + the BEGINEDIT event is enhanced + </para> + </listitem> + <listitem> <para> - xxx and xxx sss. + the ENDEDIT event is enhanced </para> + </listitem> + </itemizedlist> + </listitem></varlistentry> + </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">New samples in ooDialog 4.2.1:</emphasis></term> <listitem> <para> - xxx and xxx sss. + <computeroutput>oodialog\controls\ListView\customDrawListView.rex</computeroutput>: The customDrawListView example + demonstrates how to change the text, text color, and background color of individual rows in a list-view. </para> + <para> + <computeroutput>oodialog\controls\ListView\columnIcons.rex</computeroutput>: The columnIcons.rex example demonstrates how + to use the new LvFullRow class and how to use icons in the columns of list-view items in report view. + </para> + <para> + <computeroutput>oodialog\controls\ToolTip\toolTip.rex</computeroutput>: The toolTip.rex example demonstrates the basics + of using ToolTips in ooDialog. It includes the usage of a number of the ToolTip methods. + </para> + <para> + <computeroutput>oodialog\controls\ToolTip\customPositionToolTip.rex</computeroutput>: The customPositionToolTip.rex + example shows how to use the ToolTip class to do custom positioning of the info tips provided by the tree-view. + </para> + <para> + <computeroutput>oodialog\controls\ToolTip\manageControlTool.rex</computeroutput>: The manageControlTool.rex example shows + how to use some advanced features of the ToolTip class to provide completely customized ToolTips for a dialog control. + This example uses a tree-view control, but the techniques could be applied to any dialog control. + </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Enhanced samples in ooDialog 4.2.1:</emphasis></term> <listitem> <para> - xxx and xxx sss. + <computeroutput>oodialog\controls\TreeView\treeViewCustomDraw.rex</computeroutput>: The oodtree.rex example has been + renamed to the treeViewCustomDraw.rex and enhanced. The example has been more fully commented, uses custom draw for the + tree-view control, and has a number of small bugs fixed. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Documentation changes in ooDialog 4.2.1:</emphasis></term> @@ -2274,12 +2448,60 @@ The documentation for the connectListViewEvent and connectTreeViewEvent methods have been enhanced. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">TERM:</emphasis></term> +</variablelist> + +</section> <!-- End Section ooDialog Release 4.2.1 --> + + +</section> <!-- End Section History --> + + +<section id="sctCurrentRelease"><title>Current Release</title> +<para> + The current release of ooDialog is 4.2.2. It is a 4.2.?? level ooDialog, which means it can be installed to any ooRexx + installation that is at least version 4.??.??. The following is a brief summary of the changes in ooDialog 4.2.2 from + 4.2.1. +</para> + +<variablelist> + <varlistentry><term><emphasis role="bold">Bug Fixes in ooDialog 4.2.2:</emphasis></term> <listitem> <para> - xxx and xxx sss. + The following bugs were fixed in this release. The bug fix numbers can be used to look up details concerning the bug on + SourceForge </para> + <itemizedlist> + <listitem> + <para> + * xxx + </para> + </listitem> + <listitem> + <para> + * xxx + </para> + </listitem> + </itemizedlist> </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Feature Requests Added to ooDialog 4.2.2:</emphasis></term> + <listitem> + <para> + The following Request for Feature Ehancements were implemented in the release. Details concerning the enhancements can be + looked up on SourceForge using the listed tracker item numbers. + </para> + <itemizedlist> + <listitem> + <para> + * xxx + </para> + </listitem> + <listitem> + <para> + * xxx + </para> + </listitem> + </itemizedlist> + </listitem></varlistentry> </variablelist> </section> <!-- End Section Current Release --> |
From: <mie...@us...> - 2012-12-21 00:13:09
|
Revision: 8727 http://sourceforge.net/p/oorexx/code-0/8727 Author: miesfeld Date: 2012-12-21 00:13:05 +0000 (Fri, 21 Dec 2012) Log Message: ----------- Feature requests: #507 ooDialog - Modify the text of a list-view item and all its subitems at one time See ticket [Feature-Requests:#507] #506 Allow modifying a list-view item and all its subitems at once See ticket [Feature-Requests:#506] #505 Would like a way to prevent Enter from closing dialog when in single-line edit control See ticket [Feature-Requests:#505] #504 It would be nice to be able to store a user value as part of the LvFullRow object See ticket [Feature-Requests:#504] Modified Paths: -------------- docs/trunk/oodialog/en-US/edit.xml docs/trunk/oodialog/en-US/listview.xml docs/trunk/oodialog/en-US/overview.xml docs/trunk/oodialog/en-US/treeview.xml Modified: docs/trunk/oodialog/en-US/edit.xml =================================================================== --- docs/trunk/oodialog/en-US/edit.xml 2012-12-21 00:11:46 UTC (rev 8726) +++ docs/trunk/oodialog/en-US/edit.xml 2012-12-21 00:13:05 UTC (rev 8727) @@ -94,7 +94,7 @@ <table id="tblEditMethods" frame="all"> <title>Important Edit Methods</title> <tgroup cols="2"> -<colspec colwidth="1*" /><colspec colwidth="4*" /> +<colspec colwidth="5*" /><colspec colwidth="16*" /> <thead> <row> <entry>Method</entry> @@ -280,7 +280,7 @@ </row> <row> <entry><xref linkend="mthSetTabStops"/></entry> -<entry>setTabStops</entry> +<entry>Sets the tab stops for text copied into a multi-line edit control.</entry> </row> <row> <entry><xref linkend="mthShowBalloon"/></entry> @@ -294,6 +294,10 @@ <entry><xref linkend="mthUndo"/></entry> <entry>Undoes the last edit control operation in the edit control's undo queue.</entry> </row> +<row> +<entry><xref linkend="mthWantReturn"/></entry> +<entry>Connects the <emphasis role="italic">Enter</emphasis> keypress to a method in the Rexx dialog and prevents the edit control from sending the keypress to the dialog manager, which closes the dialog.</entry> +</row> </tbody></tgroup> </table> </section> @@ -3241,7 +3245,7 @@ </section> -<section id="mthTabEquals"><title>tab=</title> +<section id="mthTabEquals" xreflabel="tab ="><title>tab=</title> <indexterm><primary>tab=</primary><secondary>Edit class</secondary></indexterm> <indexterm><primary>Edit class</primary><secondary>tab=</secondary></indexterm> <programlisting> @@ -3253,7 +3257,7 @@ <para> The <emphasis role="italic">tab =</emphasis> method is an alias for the - <xref linkend="mthSetTabStops"/>() method. It behaves exactly the same except there is no return + <xref linkend="mthSetTabStops"/> method. It behaves exactly the same except there is no return value. </para> </section> @@ -3304,5 +3308,195 @@ </variablelist> </section> <!-- End Edit::undo() --> +<section id="mthWantReturn" xreflabel="wantReturn"><title>wantReturn</title> +<indexterm><primary>wantReturn</primary></indexterm> +<indexterm><primary>Edit class</primary><secondary>wantReturn</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--wantReturn(--+--------------+--)------------->< + +--methodName--+ +]]> +</programlisting> +<para> + Connects the <emphasis role="italic">Enter</emphasis> keypress to a method in the Rexx dialog and prevents the edit control + from sending the keypress to the dialog manager, which closes the dialog. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The single argument is: + </para> + <variablelist> + <varlistentry><term>methodName [optional]</term> + <listitem> + <para> + The name of the method in the Rexx dialog that will be invoked when the user press the enter key in the single-line + edit control. If this argument is omitted, the method name is set to <emphasis role="italic">onReturn</emphasis>. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + Returns true on success, false on error. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + By default in Windows dialogs, when the user presses the enter key, the default button is pressed. Normally the default + button is the Ok button and the dialog is closed. Usually, it is not a good idea to try and change this behavior. Most + Windows users become to depend on the behavior. + </para> + <para> + However, in rare cases, the programmer may want to change this behavior. Microsoft itself, sometimes changing this + behavior, as can be seen when in-place editing of list-view labels is done. When the user is editing a list-view label + in-place, hitting the enter key does not close the dialog, but instead accepts the current text as what the user wants. + The <emphasis role="italic">wantReturn</emphasis> method can be used in those circumstances. + </para> + <para> + A method is always connected to the Enter keypress, and invoking the <emphasis role="italic">wantReturn</emphasis> method + always prevents the Enter keypress from pressing the default button. If the programmer does not need to do anything in + the event handling method, she can simply return 0 immediately from the method. + </para> + <para> + This method is only for single-line edit controls. If the edit control is a multi-line edit control, the <emphasis + role="italic">wantReturn</emphasis> method fails and returns false. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example invokes the <emphasis role="italic">wantReturn</emphasis> method. Note that the optional <emphasis + role="italic">methodName</emphasis> argument is not used. Therefore the <emphasis role="italic">onReturn</emphasis> + method will be connected: +<programlisting> +<![CDATA[ + +::method setUpItemEdit private + expose list itemEdit + + itemEdit~wantReturn + ... + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> + + +<section id="evtEditWANTRETURN" xreflabel="WANTRETURN"><title>wantReturn Event Handler</title> +<indexterm><primary>Edit class</primary><secondary>events</secondary><tertiary>WANTRETURN</tertiary></indexterm> +<para> + The event handler for the want return event is invoked when the user presses the Enter, sometimes called the Return, key + when the connected, single-line, edit control has the focus. +</para> +<para> + The programmer must return a value from the event handler and the interpreter waits for this return. +</para> + +<programlisting> +<![CDATA[ +::method onWantReturn unguarded + use arg ctrlID, editControlObj + + return 0 +]]> +</programlisting> + +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method recieves 2 arguments: + </para> + <variablelist> + <varlistentry><term>ctrlID</term> + <listitem> + <para> + The resource <link linkend="defResourceId">ID</link> of the edit control. + </para> + </listitem></varlistentry> + <varlistentry><term>editControlObj</term> + <listitem> + <para> + The Rexx Edit control object. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + The event handler must return a value, but the operating system ignores the value of the return, so any value is okay. + Returning 0 is a good choice. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example</emphasis></term> + <listitem> + <para> + The following example shows an event handler for the return event. The dialog has a single-line entry field that lets the + user type in record number and advance to that record. Hitting enter signals that the user wants to advance to record + entered in the edit control. + </para> + <para> + Note that the processing of retrieving the new record could, theoretically, be lengthy. So, the event handler replies + early to prevent the dialog from appearing hung while the processing going on: + +<programlisting> +<![CDATA[ + +::method onReturn unguarded + expose list currentItem dbMgr + use arg id, editObj + + itemIndex = editObj~getText + max = list~items + + reply 0 + + msg = '' + if itemIndex < 1 then msg = 'List-view record item can not be less than 1' + else if itemIndex > max then msg = 'List-view record item can not be greater than' max + + if msg \== '' then do + editObj~setText(currentItem) + editObj~showBalloon('Entry Error', msg, 'ERROR') + return + end + + oldItem = currentItem + currentItem = itemIndex - 1 + + lvRow = list~getItemData(currentItem) + rec = dbMgr~getRecordForID(lvRow~userData) + + if rec == .nil then do + say 'Failed to get new record' -- TODO need message box + currentItem = oldItem + editObj~setText(currentItem) + return + end + + self~setRecordFields(rec) + self~setNavigateButtons + + self~setStateToUnchanged + + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> + +</section> <!-- End wantReturn Event Handler --> + +</section> <!-- End Edit::wantReturn() --> + + </chapter> Modified: docs/trunk/oodialog/en-US/listview.xml =================================================================== --- docs/trunk/oodialog/en-US/listview.xml 2012-12-21 00:11:46 UTC (rev 8726) +++ docs/trunk/oodialog/en-US/listview.xml 2012-12-21 00:13:05 UTC (rev 8727) @@ -479,6 +479,10 @@ <entry>Sets new attributes for a column of this list-view control when it has the report or list style.</entry> </row> <row> +<entry><xref linkend="mthModifyFullRow"/></entry> +<entry>Modifies the information for an item, and all its subitems, in a list-view using a <xref linkend="clsLvFullRow"/> object.</entry> +</row> +<row> <entry><xref linkend="mthModifyItem"/></entry> <entry>Modifies some or all of the data this list-view maintains for an item using a <xref linkend="clsLvItem"/> object.</entry> </row> @@ -571,6 +575,10 @@ <entry>Sets the width, in pixels, of a column in this list-view control that has the report or list style.</entry> </row> <row> +<entry><xref linkend="mthSetFullRowText"/></entry> +<entry>Modifies all, or some, of the text for a list-view item and its subitems using a <xref linkend="clsLvFullRow"/> object.</entry> +</row> +<row> <entry><xref linkend="mthSetHoverTime"/></entry> <entry>Used to change the hover time.</entry> </row> @@ -5234,6 +5242,102 @@ </variablelist> </section> <!-- End ListView::modifyColumnPX() --> +<section id="mthModifyFullRow" xreflabel="modifyFullRow"><title>modifyFullRow</title> +<indexterm><primary>modifyFullRow</primary></indexterm> +<indexterm><primary>ListView class</primary><secondary>modifyFullRow</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--modifyFullRow(--row--)----------------------->< +]]> +</programlisting> + +<para> + Modifies the information for an item, and all its subitems, in a list-view using a <xref linkend="clsLvFullRow"/> object. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The single argument is: + </para> + <variablelist> + <varlistentry><term>row [required]</term> + <listitem> + <para> + The <emphasis role="italic">row</emphasis> argument must either be a <computeroutput>LvFullRow</computeroutput> object, + or the zero-based index of the list-view item to be modified. + </para> + + <variablelist> + <varlistentry><term><emphasis role="bold">LvFullRow object:</emphasis></term> + <listitem> + <para> + When the <emphasis role="italic">row</emphasis> argument is a <computeroutput>LvFullRow</computeroutput> object, the + information in the list-view item is modified to match the information in the full row object. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Item index:</emphasis></term> + <listitem> + <para> + When the <emphasis role="italic">row</emphasis> argument is the index of the item to modify, the item <link + linkend="mthSetItemDataClsListView">data</link> of the list-view item <emphasis role="italic">must</emphasis> have + been assigned a <computeroutput>LvFullRow</computeroutput> object. The list-view item's information is then modified + to match the information in the assigned full row object. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + Returns true on success, false on error. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + Using an item index for the <emphasis role="italic">row</emphasis> argument can be thought of as a <emphasis + role="italic">sync</emphasis> operation. It is assumed that the programmer has changed the value of the attributes of the + <computeroutput>LvFullRow</computeroutput> object that is assigned as the item data of the list-view item. Then, invoking + the <emphasis role="italic">modifyFullRow</emphasis> method has the effect of syncing up the underlying list-view item's + information with the full row object's information. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect usage is detected. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example modifies the information for the list-view item with index 3. The item has 4 subitems and uses subitem + images. The application only wants to modify the text and image index for the item and the first subitem. The other + information of the item is left alone. The first step of getting the full row object for item 3, ensures that all the + information in the full row object matches the current state of the item. Then just the label and icon index for the item + and first subitem is changed, and the full row object is used to modify the list-view item: +<programlisting> +<![CDATA[ + + lvfull = list~getFullRow(3) + + lvFull~item~text = 'Nurse Practitioner' + lvFull~item~imageIndex = 4 + lvFull~subitem(1)~text = 'Harry' + lvFull~subitem(1)~imageIndex = 14 + + list~modifyFullRow(lvFull) + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End ListView::modifyFullRow() --> + <section id="mthModifyItem" xreflabel="modifyItem"><title>modifyItem</title> <indexterm><primary>modifyItem</primary></indexterm> <indexterm><primary>ListView class</primary><secondary>modifyItem</secondary></indexterm> @@ -6542,7 +6646,128 @@ </variablelist> </section> <!-- End ListView::setColumnWidthPX() --> +<section id="mthSetFullRowText" xreflabel="setFullRowText"><title>setFullRowText</title> +<indexterm><primary>setFullRowText</primary></indexterm> +<indexterm><primary>ListView class</primary><secondary>setFullRowText</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--setFullRowText(--row--)---------------------->< +]]> +</programlisting> +<para> + Modifies all, or some, of the text for a list-view item and its subitems using a <xref linkend="clsLvFullRow"/> object. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The single argument is: + </para> + <variablelist> + <varlistentry><term>row [required]</term> + <listitem> + <para> + The <emphasis role="italic">row</emphasis> argument must either be a <computeroutput>LvFullRow</computeroutput> object, + or the zero-based index of the list-view item whose text is to be modified. + </para> + + <variablelist> + <varlistentry><term><emphasis role="bold">LvFullRow object:</emphasis></term> + <listitem> + <para> + When the <emphasis role="italic">row</emphasis> argument is a <computeroutput>LvFullRow</computeroutput> object, the + text of the list-view item is modified to match the text in the full row object. For the item and each subitem, the + text is only modified, if that item or subitem in the <emphasis role="italic">row</emphasis> full row object has its + item <xref linkend="atrMaskClsLvi"/>, or subitem <xref linkend="atrMaskClsLvsi"/> attribute set to contain the TEXT + keyword. If the item's, or subitem's, mask does not contain the TEXT keyword, the text in the list-view item is left + unchanged. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Item index:</emphasis></term> + <listitem> + <para> + When the <emphasis role="italic">row</emphasis> argument is the index of the item to modify, the item <link + linkend="mthSetItemDataClsListView">data</link> of the list-view item <emphasis role="italic">must</emphasis> have + been assigned a <computeroutput>LvFullRow</computeroutput> object. The list-view item's text is then modified to + match the text in the assigned full row object. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + Returns true on success, false on error. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + Using an item index for the <emphasis role="italic">row</emphasis> argument can be thought of as a <emphasis + role="italic">sync</emphasis> operation. It is assumed that the programmer has changed the value of the text attributes + of the <computeroutput>LvFullRow</computeroutput> object that is assigned as the item data of the list-view item. Then, + invoking the <emphasis role="italic">modifyFullRow</emphasis> method has the effect of syncing up the underlying + list-view item's text with the full row object's text attributes. In this case, the text of the item and the text of + every subitem is set to the corresponding text value the item data's full row object. + </para> + <para> + In contrast, when a <computeroutput>LvFullRow</computeroutput> object is used as the <emphasis + role="italic">row</emphasis> argument, it is possible to only update the text for the item or subitems that need to be + updated. The example below demonstrates this technique. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect usage is detected. + </para> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example constructs a full row object for a list-view that has 6 subitems. <emphasis + role="italic">currentItem</emphasis> is the index of one of the list-view items, the item whose text might be modified. + Note that the text and mask attributes of the item and subitems of the full row are not set. The current text in all the + edit controls is collected and compared to the old values stored in the rec array. If it does not match, the text + attribute in the full row is set to the value from the edit control. In this way, when !setFullRowText() is invoked, only + the text of the item or subitems in the list-view that have actually changed are updated: +<programlisting> +<![CDATA[ + + lNameText = lNameEdit~getText~strip + fNameText = fNameEdit~getText~strip + ... + zipText = zipEdit~getText~strip + + lvFullRow = .LvFullRow~new(.LvItem~new(currentItem)) + do i = 1 to 6 + lvFullRow~addSubitem(.LvSubItem~new(currentItem, i)) + end + + if lNameText \== rec[2] then do + lvFullRow~item~text = lNameText + end + if fNameText \== rec[3] then do + lvFullRow~subItem(1)~text = fNameText + end + ... + if zipText \== rec[8] then do + lvFullRow~subItem(6)~text = zipText + end + + list~setFullRowText(lvFullRow) + + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End ListView::setFullRowText() --> + + <section id="mthSetHoverTime" xreflabel="setHoverTime"><title>setHoverTime</title> <indexterm><primary>setHoverTime</primary></indexterm> <programlisting> @@ -8840,6 +9065,818 @@ </section> <!-- End LvCustomDrawSimple Class --> +<section id="clsLvFullRow" xreflabel="LvFullRow"><title>LvFullRow Class</title> +<indexterm><primary>LvFullRow class</primary></indexterm> +<para> + A <computeroutput>LvFullRow</computeroutput> object is used in ooDialog to represent a list-view item and all subitems + of that item. A <computeroutput>LvFullRow</computeroutput> object is composed of a <xref linkend="clsLvItem"/> object whose + attributes reflect the list-view item and zero or more <xref linkend="clsLvSubItem"/> objects that reflect the subitems of + the list-view item in the <link linkend="ovvUnderlying">underlying</link> list-view. +</para> +<para> + Normally, the subitems of a list-view item are only thought about when the list-view is in report view. However, once added + to an item, the subitems exist whatever view the list-view is in. A full row object can be used to add or insert list-view + items along with all the subitems of the item, or to query information about a list-view item and its subitems. +</para> +<para> + <computeroutput>LvFullRow</computeroutput> objects also provide the infrastructure that allows the ooDialog framework to + <link linkend="mthSortItems">internally</link> sort list-view items. +</para> + + +<section id="sctInternalSorting"><title>Internal Sorting Considerations</title> +<indexterm><primary>internal sorting</primary><secondary>LvFullRow Class</secondary></indexterm> +<indexterm><primary>internal sorting</primary><secondary>ListView Class</secondary></indexterm> +<para> + The <xref linkend="mthSortItems"/> method is used to sort list-view items. One option of this method is to have the + ooDialog framework implement the sort internally. The internal sort can be significantly faster, for large lists, than + implementing the sort in Rexx. However, the internal sorting is dependent on the <computeroutput>LvFullRow</computeroutput> + class. There are a few things the Rexx programmer needs to be aware of that effect the ability of the ooDialog framework to + do an internal sort. +</para> +<para> + Any sorting of the list-view items, whether it is through a sort implemented in Rexx or the internal sort, is dependent on + <link linkend="mthSetItemDataClsListView">setting</link> a value for the item data of every list-view item. For the + internal sort to work, the item data value must be a <computeroutput>LvFullRow</computeroutput> object. There are several + approaches that could be used to assign a full row object to the item data of every list-view item. One approach would be + to iterate through all the list-view items, for each item, instantiate a full row object for the item, and use the <xref + linkend="mthSetItemDataClsListView"/> method to assign the object to the item. +</para> +<para> + However, full row objects can also be used to add items to the list-view through one the <xref linkend="mthAddFullRow"/>, + <xref linkend="mthInsertFullRow"/>, or <xref linkend="mthPrependFullRow"/> methods. A second approach is to add all + list-view items using full row objects and have the ooDialog framework set the full row object as the item data when the + item is added to the list-view. To use this technique, the programmer should set the <emphasis + role="italic">sorting</emphasis> argument to true when <link linkend="mthNewClsLvFullRow">instantiating</link> the full row + object. +</para> +<para> + In a way, a full row object is a snapshot of the information the list-view control maintains about a specific item in the + list. This information can change over time as the application is used. For instance, the text of an item could be changed. + When a full row object is assigned as the item data of a list-view item, the ooDialog framework does its best to keep the + full row object updated with any changes made to the information of the list-view item. But, there is one scenario where + this is not always possibile. The Rexx programmer needs to be aware of this and take the proper steps to keep the full row + object in synch with the list-view item. +</para> +<para> + When a subitem column in the list-view is <link linkend="mthInsertColumnPX">inserted</link> + or <link linkend="mthDeleteColumn">deleted</link>, the list-view control adds or deletes the subitems of all + items that corresponds to the colum. Every item in a list-view always has the same number of subitems. If all items in the + list-view have a <computeroutput>LvFullRow</computeroutput> object set as the item data, when a column is deleted, the full + row object will have one too many subitems. The same if a column is added, the full row object will have no knowledge of + the new subitem. <emphasis role="bold">Note</emphasis> that there is no problem the very first time a column is inserted + in a list-view and this only applies to <emphasis role="italic">subitem</emphasis> columns. The information for a + list-view item is not deleted by deleting its column, column 0. In addition, this discussion only concerns the case where + <computeroutput>LvFullRow</computeroutput> objects have been assigned to the item data of each item to faciliate internal + sorting. +</para> +<para> + Most ooDialog programs that use a list-view do not involve inserting or removing columns after the list-view items have + been added. But, for programs that do <emphasis role="italic">and</emphasis> use <computeroutput>LvFullRow</computeroutput> + objects to allow internal sorting, the programmer must take an additional step when a column is inserted or deleted. This + ensures the integrity of the full row objects. ooDialog provides 3 methods to ensure integrity when a column is inserted or + deleted: +</para> + +<variablelist> + <varlistentry><term><emphasis role="bold">The fixFullRowColumns method:</emphasis></term> + <listitem> + <para> + ooDialog provides the <xref linkend="mthFixFullRowColumns"/> method of the <computeroutput>ListView</computeroutput> + which can be used to bring all the full row objects back in sync. It must be invoked after each individual column insert + and delete to work correctly. That is, the programmer can not delete 2 columns and then invoke the <emphasis + role="italic">fixFullRowColumns</emphasis> twice. The method is invoked with the column index that was removed or added + and a second argument that signals whether the specified column was inserted. The following code snippet gives an + example: +<programlisting> +<![CDATA[ + list~insertColumnPX(2, "Phone Numbers", 155, "RIGHT") + list~fixFullRowColumns(2, .true) + +]]> +</programlisting> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">The adjustFullRows argument:</emphasis></term> + <listitem> + <para> + The methods that insert or delete columns in the list-view have an optional second argument, <emphasis + role="italic">adjustFullRows</emphasis>. If this argument is true, then the ooDialog framework is signaled to fix up the + full row objects internally when the column is added or deleted. The default for the argument is false. This is perhaps + the easist process for the programmer to use. The above example would be altered like this: +<programlisting> +<![CDATA[ + list~insertColumnPX(2, "Phone Numbers", 155, "RIGHT", .true) + +]]> +</programlisting> + The reason that the default here is false is that with very large lists, the time to fix up the full row objects can be + noticeable, .5 to 1.5 seconds for lists with over 10,000 items. Because of this, the programmer may not want the fix up + to happen during the insertion or deletion of a column. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Manual update</emphasis></term> + <listitem> + <para> + With this method, after the column insert or delete, the programmer iterates through all the list-view items, removes the + old invalid item data, creates a valid full row object, and sets the item data to the new full row object. The following + code snippet shows the procedure: +<programlisting> +<![CDATA[ + + list~deleteColumn(delCol) + + do i = 0 to list~items - 1 + list~removeItemData(i) + lvFullRow = list~getFullRow(i, .true) + list~setItemData(i, lvFullRow) + end + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> + +<section id="sctMethodsLvFullRow"><title>Method Table</title> +<para> + The following table lists the class and instance methods of the <computeroutput>LvFullRow</computeroutput> class: + +<table id="tblMethodsLvFullRow" frame="all"> <title>LvFullRow Class Method Reference</title> +<tgroup cols="2"> +<colspec colwidth="1*"/> +<colspec colwidth="4*"/> +<thead> +<row> +<entry>Method</entry> +<entry>Description</entry> +</row> +</thead> +<tbody> +<row> +<entry align="center"><emphasis role="bold">Class</emphasis></entry> +<entry align="center"><emphasis role="bold">Methods</emphasis></entry> +</row> +<row> +<entry><xref linkend="mthNewClsLvFullRow"/></entry> +<entry>Instantiates a new <computeroutput>LvFullRow</computeroutput> object.</entry> +</row> +<row> +<entry align="center"><emphasis role="bold">Attribute</emphasis></entry> +<entry align="center"><emphasis role="bold">Methods</emphasis></entry> +</row> +<row> +<entry><xref linkend="atrUserData"/></entry> +<entry></entry> +</row> +<row> +<entry align="center"><emphasis role="bold">Instance</emphasis></entry> +<entry align="center"><emphasis role="bold">Methods</emphasis></entry> +</row> +<row> +<entry><xref linkend="mthAddSubItem"/></entry> +<entry>Adds a subitem to this full row. Subitems are always added as the last subitem in the row.</entry> +</row> +<row> +<entry><xref linkend="mthInsertSubItem"/></entry> +<entry>Inserts a new subitem into this full row and adjusts the subitem indexes for all existing subitems, when needed.</entry> +</row> +<row> +<entry><xref linkend="mthItem"/></entry> +<entry>Returns the <xref linkend="clsLvItem"/> object of this full row.</entry> +</row> +<row> +<entry><xref linkend="mthRemoveSubItem"/></entry> +<entry>Removes the specified subitem from this full row.</entry> +</row> +<row> +<entry><xref linkend="mthSubItem"/></entry> +<entry>Returns the subitem specified by <emphasis role="italic">index</emphasis> of this full row, or the <computeroutput>.nil</computeroutput> object if the subitem <emphasis role="italic">index</emphasis> is not valid.</entry> +</row> +<row> +<entry><xref linkend="mthSubItems"/></entry> +<entry>Returns the count of subitems in this full row.</entry> +</row> +</tbody></tgroup> +</table> +</para> +</section> + +<section id="mthNewClsLvFullRow" xreflabel="new"><title>new (Class Method)</title> +<indexterm><primary>new</primary><secondary>LvFullRow class</secondary></indexterm> +<indexterm><primary>LvFullRow class</primary><secondary>new</secondary></indexterm> +<programlisting> +<![CDATA[ + +--------------+ + V | +>>--new(--item--+--------------+--+-----------+--)-------------->< + +--,--subItem--+ +-,-sorting-+ +]]> +</programlisting> + +<para> + Instantiates a new <computeroutput>LvFullRow</computeroutput> object. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The arguments are: + </para> + <variablelist> + <varlistentry><term>item [required]</term> + <listitem> + <para> + A <link linkend="clsLvItem">LvItem</link> object that specifies the attributes of the list-view item being added. + </para> + </listitem></varlistentry> + <varlistentry><term>subItem [optional]</term> + <listitem> + <para> + A <link linkend="clsLvSubItem">LvSubItem</link> object that specifies the attributes of a subitem of the list-view + item being added. The argument can repeat has many times as needed to specify all the subitems of the item. The + subitems are added to the item in the order of the arguments to the <emphasis role="italic">new</emphasis> method. + </para> + </listitem></varlistentry> + <varlistentry><term>sorting [optional]</term> + <listitem> + <para> + The very last argument can optionally be <computeroutput>.true</computeroutput> or + <computeroutput>.false</computeroutput> to signal that the <computeroutput>LvFullRow</computeroutput> object itself is + to be assigned as the item data value of the list-view items. This usage is explained in the remarks section. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + Returns the new <computeroutput>LvFullRow</computeroutput> object. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + Each subitem argument must be specified. If a subitem is omitted and a subitem argument follows it, a syntax + condition is raised. That is, if a subitem is specified, its preceding subitem must not have been omitted. These + statements are acceptable: + +<programlisting> +<![CDATA[ + row = .LvFullRow~new(item) + row = .LvFullRow~new(item, si1, si2) + row = .LvFullRow~new(item, si1, si2, si3) +]]> +</programlisting> + + These statements will raise a syntax codition: + +<programlisting> +<![CDATA[ + row = .LvFullRow~new(item, , si2) + row = .LvFullRow~new(item, si1, , si3) +]]> +</programlisting> + + </para> + <para> + In addition to specifying <computeroutput>LvSubItem</computeroutput> objects, the last argument can be either true or + false. Recall that the list-view control allows the programmer to <link linkend="mthSetItemDataClsListView">attach</link> + an item data value to any or all of the list-view items. If the item data for every list-view item is a + <computeroutput>LvFullRow</computeroutput> object, the ooDialog framework can perform internal <link + linkend="mthSortItems">sorting</link> of the list-view items. The last argument can be true to specify that the + <computeroutput>LvFullRow</computeroutput> object being instantiated should be set as the item data value for the + list-view item the <computeroutput>LvFullRow</computeroutput> object represents. + </para> + <para> + This feature is really only of use if the full row object is used to add or insert an item into the list-view. If the + full row object is not to be used to add an item to the list-view, then there is no reason to use the last argument of + true or false. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect usage is detected. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example shows a method that creates an array of list-view full rows from NFL football player data. The array is + later used to insert the rows into a list-view control. +<programlisting> +<![CDATA[ + +::method getPlayers private + + players = .NFLPlayer~playersFromDataSource("nflPlayers.txt") + + self~masterList = .MasterPlayerList~new(players) + + playerRows = .array~new(players~items) + do i = 1 to players~items + j = i - 1 + p = players[i] + lvi = .LvItem~new(j, , p~name, , p) + lvsi1 = .LvSubItem~new(j, 1, p~team) + lvsi2 = .LvSubItem~new(j, 2, p~position) + lvsi3 = .LvSubItem~new(j, 3, p~rating) + + r = .LvFullRow~new(lvi, lvsi1, lvsi2, lvsi3) + playerRows[i] = r + end + + return playerRows + + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End LvFullRow::new() --> + +<section id="atrUserData" xreflabel="userData"><title>userData (Attribute)</title> +<indexterm><primary>userData</primary></indexterm> +<indexterm><primary>LvFullRow class</primary><secondary>userData</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--userData----------------------------------------------------->< + +>>--userData = varName------------------------------------------->< + +]]> +</programlisting> + +<para> + The <emphasis role="italic">userData</emphasis> attribute allows the programmer to associate some data with a + <computeroutput>LvFullRow</computeroutput> object. The data assigned can be any Rexx object the programmer desires. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">userData get:</emphasis></term> + <listitem> + <para> + Returns the user data object assigned to this full row object, or the <computeroutput>.nil</computeroutput> object if no + user data has been associated with this full row. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">userData set:</emphasis></term> + <listitem> + <para> + Assigns a user data object to this full row object. There is no restriction on what type of object this may be. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + The Windows list-view control allows an <link linkend="mthSetItemDataClsListView">data</link> value to be associated with + any or all items in the list-view. This is convenient for a number of things. However, if the ooDialog program is using + <computeroutput>LvFullRow</computeroutput> objects for <link linkend="sctInternalSorting">internal</link> sorting, the + full row object is assigned as the data value for each item. This prevents the programmer from using the list-view's item + data for some other purpose. The <emphasis role="italic">userData</emphasis> attribute is provided for these + circumstances. The programmer assigns a value to the <emphasis role="italic">userData</emphasis> attribute of the full + row object that needs to be associated with the list-view item. Since the full row object is assigned to the list-view + item data, the value assigned to the <emphasis role="italic">userData</emphasis> attribute is in effect assigned to the + list-view item. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example constructs a full row object to be displayed as an item in a list-view. The data for each item comes from + records in a database. In order to keep track of which record in the database corresponds to each list-view item, the + record ID is stored in the <emphasis role="italic">userData</emphasis> attribute of the full row object. The value at + index 1 of the rec array is the rowid of the record: +<programlisting> +<![CDATA[ + +::method fullRowFromRecord unguarded + use strict arg rec, index = 0 + + lvItem = .LvItem~new(index, rec[2]) + lvSub1 = .LvSubItem~new(index, 1, rec[3]) + lvSub2 = .LvSubItem~new(index, 2, rec[4]) + lvSub3 = .LvSubItem~new(index, 3, rec[6]) + lvSub4 = .LvSubItem~new(index, 4, rec[7]) + lvSub5 = .LvSubItem~new(index, 5, rec[8]) + + lvFullRow = .LvFullRow~new(lvItem, lvSub1, lvSub2, lvSub3, lvSub4, lvSub5, .true) + lvFullRow~userData = rec[1] + + return lvFullRow + + + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End LvFullRow::userData() [attribute] --> + +<section id="mthAddSubItem" xreflabel="addSubItem"><title>addSubItem</title> +<indexterm><primary>addSubItem</primary></indexterm> +<indexterm><primary>LvFullRow class</primary><secondary>addSubItem</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--addSubItem(--subitem--)---------------------->< +]]> +</programlisting> + +<para> + Adds a subitem to this full row. Subitems are always added as the last subitem in the row. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The single argument is: + <variablelist> + <varlistentry><term>subitem [required]</term> + <listitem> + <para> + A <xref linkend="clsLvSubItem"/> object that specifies the subitem being added. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + Returns the index of the added subitem on success, or 0 on error. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + The <emphasis role="italic">addSubItem</emphasis> method allows the programmer to add subitems to the full row after the + <computeroutput>LvFullRow</computeroutput> object has been instantiated. Typically, all subitems would be added to the + full row at the time of instantiation through the <xref linkend="mthNewClsLvFullRow"/> method. In addition to the + <emphasis role="italic">addSubItem</emphasis> method, the <xref linkend="mthInsertSubItem"/> method can be used to insert + a subitem into the middle of the subitem list. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect usage is detected. + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End LvFullRow::addSubItem() --> + +<section id="mthInsertSubItem" xreflabel="insertSubItem"><title>insertSubItem</title> +<indexterm><primary>insertSubItem</primary></indexterm> +<indexterm><primary>ListView class</primary><secondary>insertSubItem</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--insertSubItem(--subItem--,--colIndex--)------>< +]]> +</programlisting> + +<para> + Inserts a new subitem into this full row and adjusts the subitem indexes for all existing subitems, when needed. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The arguments are: + </para> + <variablelist> + <varlistentry><term>subitem [required]</term> + <listitem> + <para> + A <xref linkend="clsLvSubItem"/> object that specifies the subitem being inserted. + </para> + </listitem></varlistentry> + <varlistentry><term>colIndex [required]</term> + <listitem> + <para> + The one-based index that specifies which column the subitem is inserted at. The index can not be 0 and can not be + greater than the current count of subitems + 1. That is, a subitem can not be inserted in a way that leaves the + subitems non-contiguous. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + Returns true on success, false on error. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + The <emphasis role="italic">insertSubItem</emphasis> method allows the programmer to add subitems to the full row after + the <computeroutput>LvFullRow</computeroutput> object has been instantiated. Typically, all subitems would be added to + the full row at the time of instantiation through the <xref linkend="mthNewClsLvFullRow"/> method. In addition to the + <emphasis role="italic">insertSubItem</emphasis> method, the <xref linkend="mthAddSubItem"/> method can be used to add a + subitem to the end of the subitem list. + </para> + <para> + Inserting a new column into the middle of the exsiting subitems, will of course make the subitem index in the subitems + following the newly inserted subitem invalid. The ooDialog framework will automatically fix the subitem indexes where + needed. In addition, both the <xref linkend="atrItemClsLvSi"/> and <xref linkend="atrSubItemClsLvSi"/> attributes in the + newly inserted <emphasis role="italic">subitem</emphasis> object are set to the collect values automatically. Because of + this, the <emphasis role="italic">subitem</emphasis> object argument does not necessarily have to have correct item and + subitem index values. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect usage is detected. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example inserts a new subitem for column 3. Notice that when instantiating the + <computeroutput>LvSubItem</computeroutput> object, the code does not bother with setting the <emphasis + role="italic">item</emphasis> and <emphasis role="italic">subitem</emphasis> correctly. Rather it relies on the <emphasis + role="italic">insertSubItem</emphasis> method to set them correctly: +<programlisting> +<![CDATA[ + + lvSubItem = .LvSubItem~new(1, 1, 'Apartment #13', 2) + lvFull~insertSubItem(lvSubItem, 3) + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End ListView::insertSubItem() --> + + +<section id="mthItem" xreflabel="item"><title>item</title> +<indexterm><primary>item</primary></indexterm> +<indexterm><primary>LvFullRow class</primary><secondary>item</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--item----------------------------------------->< +]]> +</programlisting> + +<para> + Returns the <xref linkend="clsLvItem"/> object of this full row. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + There are no arguments for this method. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + Returns the <emphasis role="italic">LvItem</emphasis> object for this full row. All full rows must have an item object so + there is no way for this method to fail. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + Additional comments. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example gets the <computeroutput>LvFullRow</computeroutput> for the item at index 5 of the list-view. It then gets + the <computeroutput>LvItem</computeroutput> object and prints its information out to the display +<programlisting> +<![CDATA[ + + lvfull = list~getFullRow(5) + lvitem = lvFull~item + self~printItem(lvitem) + +/* Output might be for example: + +Item columnFormats: an Array +Item columns: an Array +Item columns count: 0 +Item groupID: -2 +Item imageIndex: 3 +Item indent: 0 +Item index: 5 +Item itemData: a LvFullRow +Item itemState: FOCUSED SELECTED +Item itemStateMask: +Item mask: GROUPID IMAGE PARAM TEXT +Item overlayImageIndex: 0 +Item stateImageIndex: 0 +Item text: Clerk + +*/ +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End LvFullRow::item() --> + +<section id="mthRemoveSubItem" xreflabel="removeSubItem"><title>removeSubItem</title> +<indexterm><primary>removeSubItem</primary></indexterm> +<indexterm><primary>LvFullRow class</primary><secondary>removeSubItem</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--removeSubItem(--index--)--------------------->< +]]> +</programlisting> + +<para> + Removes the specified subitem from this full row. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The arguments are: + <variablelist> + <varlistentry><term>index [required]</term> + <listitem> + <para> + The index of the subitem to remove. This is the same as the column index for the subitem. <emphasis + role="italic">index</emphasis> must be a valid, existing, subitem index. This means it can not be 0, or greater than + the count of current subitems. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + Returns the removed <computeroutput>LvSubItem</computeroutput> object on success, or the + <computeroutput>.nil</computeroutput> object on error. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + The <emphasis role="italic">removeSubItem</emphasis> method allows the programmer to remove subitem from the full row + after the <computeroutput>LvFullRow</computeroutput> object has been instantiated. Typically, all subitems would be set + correctly in the full row at the time of instantiation through the <xref linkend="mthNewClsLvFullRow"/> method. + </para> + <para> + Removing a column from the middle of the exsiting subitems, will of course make the subitem index in the subitems + following the removed subitem invalid. The ooDialog framework will automatically fix the subitem indexes where needed. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when incorrect usage is detected. + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End LvFullRow::removeSubItem() --> + +<section id="mthSubItem" xreflabel="subItem"><title>subItem</title> +<indexterm><primary>subItem</primary></indexterm> +<indexterm><primary>LvFullRow class</primary><secondary>subItem</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--subItem(--index--)--------------------------->< +]]> +</programlisting> + +<para> + Returns the subitem specified by <emphasis role="italic">index</emphasis> of this full row, or the + <computeroutput>.nil</computeroutput> object if the subitem <emphasis role="italic">index</emphasis> is not valid. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The single argument is: + <variablelist> + <varlistentry><term>index [required]</term> + <listitem> + <para> + The one-based index of the subitem requested. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + Returns the requested <xref linkend="clsLvSubItem"/> object on success, or the <computeroutput>.nil</computeroutput> + object on error. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example gets the subitem in column 3 of the item at index 4 in the list-view and prints out its information: +<programlisting> +<![CDATA[ + + + lvfull = list~getFullRow(4) + subItem = lvFull~subItem(3) + self~printSubItem(subItem) + +/* Output might be: + +Subitem imageIndex: 11 +Subitem item: 4 +Subitem mask: IMAGE TEXT +Subitem subitem: 3 +Subitem text: ca...@sh... + +*/ +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End LvFullRow::subItem() --> + +<section id="mthSubItems" xreflabel="subItems"><title>subItems</title> +<indexterm><primary>subItems</primary></indexterm> +<indexterm><primary>LvFullRow class</primary><secondary>subItems</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--subItems------------------------------------->< +]]> +</programlisting> + +<para> + Returns the count of subitems in this full row. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + There are no arguments for this method. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + Returns the count of subitems in this full row. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example ... +<programlisting> +<![CDATA[ + + lvfull = list~getFullRow(4) + if lvfull~subitems == 0 then do + say 'No subitems for row at index 4' + return + end + + do i = 1 to lvfull~subitems + subItem = lvFull~subItem(i) + self~printSubItem(subItem) + end + +/* Output might be: + +Item imageIndex: 13 +Item item: 4 +Item mask: IMAGE TEXT +Item subitem: 1 +Item text: Cienna + +Item imageIndex: 18 +Item item: 4 +Item mask: IMAGE TEXT +Item subitem: 2 +Item text: Acer + +Item imageIndex: 11 +Item item: 4 +Item mask: IMAGE TEXT +Item subitem: 3 +Item text: ca...@sh... + +*/ +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End LvFullRow::subItems() --> + +</section> <!-- End LvFullRow Class --> + + <section id="clsLvItem" xreflabel="LvItem"><title>LvItem Class</title> <indexterm><primary>LvItem class</primary></indexterm> <para> @@ -10416,732 +11453,6 @@ </section> <!-- End LvItem Class --> -<section id="clsLvFullRow" xreflabel="LvFullRow"><title>LvFullRow Class</title> -<indexterm><primary>LvFullRow class</primary></indexterm> -<para> - A <computeroutput>LvFullRow</computeroutput> object is used in ooDialog to represent a list-view item and all subitems - of that item. A <computeroutput>LvFullRow</computeroutput> object is composed of a <xref linkend="clsLvItem"/> object whose - attributes reflect the list-view item and zero or more <xref linkend="clsLvSubItem"/> objects that reflect the subitems of - the list-view item in the <link linkend="ovvUnderlying">underlying</link> list-view. -</para> -<para> - Normally, the subitems of a list-view item are only thought about when the list-view is in report view. However, once added - to an item, the subitems exist whatever view the list-view is in. A full row object can be used to add or insert list-view - items along with all the subitems of the item, or to query information about a list-view item and its subitems. -</para> -<para> - <computeroutput>LvFullRow</computeroutput> objects also provide the infrastructure that allows the ooDialog framework to - <link linkend="mthSortItems">internally</link> sort list-view items. -</para> - - -<section id="sctInternalSorting"><title>Internal Sorting Considerations</title> -<indexterm><primary>internal sorting</primary><secondary>LvFullRow Class</secondary></indexterm> -<indexterm><primary>internal sorting</primary><secondary>ListView Class</secondary></indexterm> -<para> - The <xref linkend="mthSortItems"/> method is used to sort list-view items. One option of this method is to have the - ooDialog framework implement the sort internally. The internal sort can be significantly faster, for large lists, than - implementing the sort in Rexx. However, the internal sorting is dependent on the <computeroutput>LvFullRow</computeroutput> - class. There are a few things the Rexx programmer needs to be aware of that effect the ability of the ooDialog framework to - do an internal sort. -</para> -<para> - Any sorting of the list-view items, whether it is through a sort implemented in Rexx or the internal sort, is dependent on - <link linkend="mthSetItemDataClsListView">setting</link> a value for the item data of every list-view item. For the - internal sort to work, the item data value must be a <computeroutput>LvFullRow</computeroutput> object. There are several - approaches that could be used to assign a full row object to the item data of every list-view item. One approach would be - to iterate through all the list-view items, for each item, instantiate a full row object for the item, and use the <xref - linkend="mthSetItemDataClsListView"/> method to assign the object to the item. -</para> -<para> - However, full row objects can also be used to add items to the list-view through one the <xref linkend="mthAddFullRow"/>, - <xref linkend="mthInsertFullRow"/>, or <xref linkend="mthPrependFullRow"/> methods. A second approach is to add all - list-view items using full row objects and have the ooDialog framework set the full row object as the item data when the - item is added to the list-view. To use this technique, the programmer should set the <emphasis - role="italic">sorting</emphasis> argument to true when <link linkend="mthNewClsLvFullRow">instantiating</link> the full row - object. -</para> -<para> - In a way, a full row object is a snapshot of the information the list-view control maintains about a specific item in the - list. This information can change over time as the application is used. For instance, the text of an item could be changed. - When a full row object is assigned as the item data of a list-view item, the ooDialog framework does its best to keep the - full row object updated with any changes made to the information of the list-view item. But, there is one scenario where - this is not always possibile. The Rexx programmer needs to be aware of this and take the proper steps to keep the full row - object in synch with the list-view item. -</para> -<para> - When a subitem column in the list-view is <link linkend="mthInsertColumnPX">inserted</link> - or <link linkend="mthDeleteColumn">deleted</link>, the list-view control adds or deletes the subitems of all - items that corresponds to the colum. Every item in a list-view always has the same number of subitems. If all items in the - list-view have a <computeroutput>LvFullRow</computeroutput> object set as the item data, when a column is deleted, the full - row object will have one too many subitems. The same if a column is added, the full row object will have no knowledge of - the new subitem. <emphasis role="bold">Note</emphasis> that there is no problem the very first time a column is inserted - in a list-view and this only applies to <emphasis role="italic">subitem</emphasis> columns. The information for a - list-view item is not deleted by deleting its column, column 0. In addition, this discussion only concerns the case where - <computeroutput>LvFullRow</computeroutput> objects have been assigned to the item data of each item to faciliate internal - sorting. -</para> -<para> - Most ooDialog programs that use a list-view do not involve inserting or removing columns after the list-view items have - been added. But, for programs that do <emphasis role="italic">and</emphasis> use <computeroutput>LvFullRow</computeroutput> - objects to allow internal sorting, the programmer must take an additional step when a column is inserted or deleted. This - ensures the integrity of the full row objects. ooDialog provides 3 methods to ensure integrity when a column is inserted or - deleted:... [truncated message content] |