From: <mie...@us...> - 2011-11-30 23:41:52
|
Revision: 7315 http://oorexx.svn.sourceforge.net/oorexx/?rev=7315&view=rev Author: miesfeld Date: 2011-11-30 23:41:43 +0000 (Wed, 30 Nov 2011) Log Message: ----------- Continue ooDialog doc update Modified Paths: -------------- docs/trunk/oodialog/dataAttributes.xml docs/trunk/oodialog/finished.list docs/trunk/oodialog/resources.xml docs/trunk/oodialog/trackbar.xml docs/trunk/oodialog/windowBase.xml docs/trunk/oodialog/windowBaseDCO.xml docs/trunk/oodialog/windowExtensions.xml Modified: docs/trunk/oodialog/dataAttributes.xml =================================================================== --- docs/trunk/oodialog/dataAttributes.xml 2011-11-29 23:17:32 UTC (rev 7314) +++ docs/trunk/oodialog/dataAttributes.xml 2011-11-30 23:41:43 UTC (rev 7315) @@ -443,12 +443,13 @@ </para> <para> The abstraction that there are only two objects, the Rexx dialog object and the underlying operating system dialog, is - a little outdated. In this abstraction, the state of a dialog control can only be represented by a single string, and - the state must be transferred back and forth through the dialog object. The abstraction works somewhat for simple - controls like a check box, a radio button, or an edit control. However it quickly starts to break down with more - complex controls like tree views and list views. Indeed, when the more complicated controls were added to ooDialog, - there were no get and set data methods implemente for them. There is no <emphasis - role="italic">getTreeViewData</emphasis> or <emphasis role="italic">setListViewData</emphasis> method. + a little outdated. In this abstraction, the state of a dialog control must be transferred back and forth through the + dialog object. In addition, the original users of the abstraction believed the <emphasis role="italic">data</emphasis> + of a dialog control could only be represented by a single string. The abstraction works somewhat for simple controls + like a check box, a radio button, or an edit control. However it quickly starts to break down with more complex + controls like tree views and list views. Indeed, when the more complicated controls were added to ooDialog, + there were no get and set data methods implemented for them. There is no <emphasis + role="italic">getTreeViewData</emphasis> or <emphasis role="italic">setListViewData</emphasis> methods. </para> <para> A more flexible abstraction is that everything is an object, that all the dialog controls are objects. In this @@ -596,21 +597,21 @@ automatic detection is off. </para> -<section id="mthConnectRadioButton"><title>connectRadioButton</title> -<indexterm><primary>connectRadioButton</primary></indexterm> -<indexterm><primary>dialog object</primary><secondary>connectRadioButton</secondary></indexterm> +<section id="mthConnectCheckBox"><title>connectCheckBox</title> +<indexterm><primary>connectCheckBox</primary></indexterm> +<indexterm><primary>dialog object</primary><secondary>connectCheckBox</secondary></indexterm> <programlisting> <![CDATA[ ->>--connectRadioButton(--id--+-------------------+--)----------->< - +-,--attributeName--+ +>>--connctChectBox(--id--+-------------------+--)--------------->< + +-,--attributeName--+ ]]> </programlisting> <para> - The <emphasis role="italic">connectRadioButton</emphasis> method uses the resource id of a radio button control to - connect the control in the underlying dialog to a newly created <link - linkend="sctUnderstandingDataAttributes">data attribute</link> in the Rexx dialog object. + The <emphasis role="italic">connectCheckBox</emphasis> method connects a check box in the underlying dialog, through + its resource ID, to a newly created <link linkend="sctUnderstandingDataAttributes">data attribute</link> in the Rexx + dialog object. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -621,7 +622,7 @@ <varlistentry><term>id [required]</term> <listitem> <para> - The resource ID of the radio button control to be connected. Can be numeric or symbolic. + The resource ID of the check box control to be connected. Can be numeric or symbolic. </para> </listitem></varlistentry> <varlistentry><term>attributeName [optional]</term> @@ -663,17 +664,20 @@ <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - The attribute has to be synchronized with the radio button control manually. This can be done globally with the - <link linkend="mthSetData">setData</link> and <link linkend="mthGetData">getData</link> methods. For a finer grain - of control use the <link linkend="mthSetDataAttribute">setDataAttribute</link>() or <link - linkend="mthGetDataAttribute">getDataAttribute</link>() methods. + The attribute has to be synchronized with the check box control manually. This can be done globally with the <link + linkend="mthSetData">setData</link> and <link linkend="mthGetData">getData</link> methods. For a finer grain of + control use the <link linkend="mthSetCheckBoxData">setCheckBoxData</link> or <link + linkend="mthGetCheckBoxData">getCheckBoxData</link>. The<link + linkend="mthSetDataAttribute">setDataAttribute</link>() or <link + linkend="mthGetDataAttribute">getDataAttribute</link>() methods could also be used. </para> <para> - The <emphasis role="italic">data</emphasis> of a <link linkend="clsRadioButton">radio button</link> is defined to - be the its check state. This is 0 for not checked and 1 for checked. + The <emphasis role="italic">data</emphasis> of a <link linkend="clsCheckBox">check box</link> is defined to be its + check state. For normal check boxes this is 0 for not checked and 1 for checked. Three-state check boxes have the + additional indeterminate state. The value for the indeterminate state is 2. </para> <para> - The <emphasis role="italic">connectRadioButton</emphasis> method should only be used when automatic data <link + The <emphasis role="italic">connectCheckBox</emphasis> method should only be used when automatic data <link linkend="paraAutomaticDataDetection">detection</link> is off. </para> </listitem></varlistentry> @@ -682,37 +686,37 @@ <para> The <link linkend="exampleConnectEdit">example</link> for the <emphasis role="italic">connectEdit</emphasis> method demonstrates all the pertinent steps to manually connect and use a data attribute for a dialog control. Simply - substitute a radio button for the edit control. + substitute a check box for the edit control. </para> </listitem></varlistentry> </variablelist> -</section> +</section> <!-- End dialog object::connectCheckBox() --> -<section id="mthConnectCheckBox"><title>connectCheckBox</title> -<indexterm><primary>connectCheckBox</primary></indexterm> -<indexterm><primary>dialog object</primary><secondary>connectCheckBox</secondary></indexterm> + +<section id="mthConnectComboBox"><title>connectComboBox</title> +<indexterm><primary>connectComboBox</primary></indexterm> +<indexterm><primary>dialog object</primary><secondary>connectComboBox</secondary></indexterm> <programlisting> <![CDATA[ ->>--connctChectBox(--id--+-------------------+--)--------------->< - +-,--attributeName--+ +>>--connectComboBox(--id--+------------------+--)--------------->< + +-,-attributeName--+ ]]> </programlisting> <para> - The <emphasis role="italic">connectCheckBox</emphasis> method connects a check box in the underlying dialog, through - its resource ID, to a newly created <link linkend="sctUnderstandingDataAttributes">data attribute</link>. + The <emphasis role="italic">connectComboBox</emphasis> method creates a <link + linkend="sctUnderstandingDataAttributes">data attribute</link> in the Rexx dialog object and connects it to a + combo box control in the underlying dialog using its resource id. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> - <para> - The arguments are: <variablelist> <varlistentry><term>id [required]</term> <listitem> <para> - The resource ID of the check box control to be connected. Can be numeric or symbolic. + The resource ID of the combo box control to be connected. Can be numeric or symbolic. </para> </listitem></varlistentry> <varlistentry><term>attributeName [optional]</term> @@ -723,7 +727,6 @@ </para> </listitem></varlistentry> </variablelist> - </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> @@ -754,18 +757,19 @@ <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - The attribute has to be synchronized with the check box control manually. This can be done globally with the <link + The attribute has to be synchronized with the combo box control manually. This can be done globally with the <link linkend="mthSetData">setData</link> and <link linkend="mthGetData">getData</link> methods. For a finer grain of - control use the <link linkend="mthSetDataAttribute">setDataAttribute</link>() or <link - linkend="mthGetDataAttribute">getDataAttribute</link>() methods. + control use the <link linkend="mthSetComboBoxData">setComboBoxData</link> or <link + linkend="mthGetComboBoxData">getComboBoxData</link> methods. The <link + linkend="mthSetDataAttribute">setDataAttribute</link>() or <link + linkend="mthGetDataAttribute">getDataAttribute</link>() methods can also be used. </para> <para> - The <emphasis role="italic">data</emphasis> of a <link linkend="clsCheckBox">check box</link> is defined to be the - its check state. For normal check boxes this is 0 for not checked and 1 for checked. Three-state check boxes have - the additional indeterminate state. The value for the indeterminate state is 2. + The <emphasis role="italic">data</emphasis> of a <link linkend="clsComboBox">combo box</link> is defined to be the + text in the selection field or the selected combo box item. </para> <para> - The <emphasis role="italic">connectCheckBox</emphasis> method should only be used when automatic data <link + The <emphasis role="italic">connectComboBox</emphasis> should only be used when automatic data <link linkend="paraAutomaticDataDetection">detection</link> is off. </para> </listitem></varlistentry> @@ -774,27 +778,27 @@ <para> The <link linkend="exampleConnectEdit">example</link> for the <emphasis role="italic">connectEdit</emphasis> method demonstrates all the pertinent steps to manually connect and use a data attribute for a dialog control. Simply - substitute a check box for the edit control. + substitute a combo box for the edit control. </para> </listitem></varlistentry> </variablelist> -</section> +</section> <!-- End dialog object::connectComboBox() --> -<section id="mthConnectEdit"><title>connectEdit</title> -<indexterm><primary>connectEdit</primary></indexterm> -<indexterm><primary>dialog object</primary><secondary>connectEdit</secondary></indexterm> + +<section id="mthConnectDateTimePicker"><title>connectDateTimePicker</title> +<indexterm><primary>connectDateTimePicker</primary></indexterm> +<indexterm><primary>dialog object</primary><secondary>connectDateTimePicker</secondary></indexterm> <programlisting> <![CDATA[ ->>--connectEdit(--id--+------------------+--)---->< - +-,--attributeName-+ - +>>--connectDateTimePicker(--id--+------------------+--)--------->< + +-,--attributeName-+ ]]> </programlisting> <para> - The <emphasis role="italic">connectEdit</emphasis> method creates a new <link - linkend="sctUnderstandingDataAttributes">data</link> attribute in the Rexx dialog object and connects it to the - underlying edit control using its resource id. + The <emphasis role="italic">connectDateTimePicke</emphasis> method connects a date time picker control in the + underlying dialog, through its resource ID, to a newly created <link linkend="sctUnderstandingDataAttributes">data + attribute</link> in the Rexx dialog object. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -805,7 +809,7 @@ <varlistentry><term>id [required]</term> <listitem> <para> - The resource ID of the edit control to be connected. Can be numeric or symbolic. + The resource ID of the date time picker control to be connected. Can be numeric or symbolic. </para> </listitem></varlistentry> <varlistentry><term>attributeName [optional]</term> @@ -847,97 +851,59 @@ <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - The attribute has to be synchronized with the edit control manually. This can be done globally with the <link - linkend="mthSetData">setData</link> and <link linkend="mthGetData">getData</link> methods. For a finer grain of - control use the <link linkend="mthSetDataAttribute">setDataAttribute</link>() or <link + The attribute has to be synchronized with the date time control manually. This can be done globally with the + <link linkend="mthSetData">setData</link> and <link linkend="mthGetData">getData</link> methods. For a finer + grain of control use the <link linkend="mthSetDataAttribute">setDataAttribute</link>() or <link linkend="mthGetDataAttribute">getDataAttribute</link>() methods. </para> <para> - The <emphasis role="italic">data</emphasis> of an edit control is defined to be the text entered in the control. - If there is no text, the data is the empty string. + The <emphasis role="italic">data</emphasis> of a <link linkend="clsDateTimePicker">date time picker</link> is + defined to be a <computeroutput>DateTime</computeroutput> object that represents it currently selected date and + time. </para> <para> - The <emphasis role="italic">connectEdit</emphasis> should only be used when automatic data <link + The <emphasis role="italic">connectDateTimePicker</emphasis> method should only be used when automatic data <link linkend="paraAutomaticDataDetection">detection</link> is off. </para> </listitem></varlistentry> - <varlistentry id="exampleConnectEdit"><term><emphasis role="bold">Example:</emphasis></term> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - In the following example, the edit control with symbolic resource ID IDC_EDIT is connected to the Rexx dialog - object's <emphasis role="italic">NAME</emphasis> attribute. The connection process creates the data attribute. The - string: <emphasis role="italic">Put your name here</emphasis> is assigned to the newly created data attribute. When - the dialog is executed, the underlying edit control is manually synchronized with the attribute. This has the - effect of setting the text of the edit control to the value of the attribute, which is the string, Put your name - here. + The <link linkend="exampleConnectEdit">example</link> for the <emphasis role="italic">connectEdit</emphasis> method + demonstrates all the pertinent steps to manually connect and use a data attribute for a dialog control. Simply + substitute a date time picker for the edit control. </para> - <para> - When the dialog is closed by the user with an <emphasis role="italic">ok</emphasis> command, the data attribute is - manually synchronized with the state of the edit control. The state of an edit control is defined to be the text - within the control. This synchronization has the effect of copying whatever text is in the edit control to the data - attribute. Then, when the dialog has terminated, the name the user entered is displayed. (Of course the user may not - have entered her name. What is displayed is whatever the text in the edit control was when the dialog was closed.) - -<programlisting> -<![CDATA[ - - dlg = .NameDlg~new("nameExample.dll", IDD_DIALOG1, , "nameExample.h" ) - - if dlg~initCode == 0 then do - dlg~noAutoDetection - dlg~connectEdit(IDC_EDIT, "NAME") - dlg~name = "Put your name here" - - ret = dlg~execute("SHOWTOP", IDI_DLG_OOREXX) - - if ret == 1 then say "The user's name is:" dlg~name - else say "The user canceled." - end - -return 0 - -::requires "ooDialog.cls" - -::class 'NameDlg' subclass ResDialog - -::method initDialog - self~setDataAttribute("NAME") - -::method ok - self~getDataAttribute("NAME") - self~ok:super - -]]> - </programlisting> - </para> </listitem></varlistentry> </variablelist> -</section> +</section> <!-- End dialog object::connectDateTimePicker() --> -<section id="mthConnectComboBox"><title>connectComboBox</title> -<indexterm><primary>connectComboBox</primary></indexterm> -<indexterm><primary>dialog object</primary><secondary>connectComboBox</secondary></indexterm> + +<section id="mthConnectEdit"><title>connectEdit</title> +<indexterm><primary>connectEdit</primary></indexterm> +<indexterm><primary>dialog object</primary><secondary>connectEdit</secondary></indexterm> <programlisting> <![CDATA[ ->>--connectComboBox(--id--+------------------+--)--------------->< - +-,-attributeName--+ +>>--connectEdit(--id--+------------------+--)---->< + +-,--attributeName-+ ]]> </programlisting> <para> - The <emphasis role="italic">connectComboBox</emphasis> method creates a <link - linkend="sctUnderstandingDataAttributes">data attribute</link> in the Rexx dialog object and connects it to a - combo box control in the underlying dialog using its resource id. + The <emphasis role="italic">connectEdit</emphasis> method creates a new <link + linkend="sctUnderstandingDataAttributes">data</link> attribute in the Rexx dialog object and connects it to the + underlying edit control using its resource id. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> + <para> + The arguments are: <variablelist> <varlistentry><term>id [required]</term> <listitem> <para> - The resource ID of the combo box control to be connected. Can be numeric or symbolic. + The resource ID of the edit control to be connected. Can be numeric or symbolic. </para> </listitem></varlistentry> <varlistentry><term>attributeName [optional]</term> @@ -948,6 +914,7 @@ </para> </listitem></varlistentry> </variablelist> + </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> @@ -978,31 +945,76 @@ <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - The attribute has to be synchronized with the combo box control manually. This can be done globally with the <link + The attribute has to be synchronized with the edit control manually. This can be done globally with the <link linkend="mthSetData">setData</link> and <link linkend="mthGetData">getData</link> methods. For a finer grain of - control use the <link linkend="mthSetDataAttribute">setDataAttribute</link>() or <link - linkend="mthGetDataAttribute">getDataAttribute</link>() methods. + control use the <link linkend="mthSetEditData">setEditData</link> or <link + linkend="mthGetEditData">getEditData</link> methods. The <link + linkend="mthSetDataAttribute">setDataAttribute</link>() or <link + linkend="mthGetDataAttribute">getDataAttribute</link>() methods can also be used. </para> <para> - The <emphasis role="italic">data</emphasis> of a <link linkend="clsComboBox">combo box</link> is defined to be the - text in the selection field or the selected list item. + The <emphasis role="italic">data</emphasis> of an edit control is defined to be the text entered in the control. + If there is no text, the data is the empty string. </para> <para> - The <emphasis role="italic">connectComboBox</emphasis> should only be used when automatic data <link + The <emphasis role="italic">connectEdit</emphasis> should only be used when automatic data <link linkend="paraAutomaticDataDetection">detection</link> is off. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <varlistentry id="exampleConnectEdit"><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - The <link linkend="exampleConnectEdit">example</link> for the <emphasis role="italic">connectEdit</emphasis> method - demonstrates all the pertinent steps to manually connect and use a data attribute for a dialog control. Simply - substitute a combo box for the edit control. + In the following example, the edit control with symbolic resource ID IDC_EDIT is connected to the Rexx dialog + object's <emphasis role="italic">NAME</emphasis> attribute. The connection process creates the data attribute. The + string: <emphasis role="italic">Put your name here</emphasis> is assigned to the newly created data attribute. When + the dialog is executed, the underlying edit control is manually synchronized with the attribute. This has the + effect of setting the text of the edit control to the value of the attribute, which is the string, Put your name + here. </para> + <para> + When the dialog is closed by the user with an <emphasis role="italic">ok</emphasis> command, the data attribute is + manually synchronized with the state of the edit control. The state of an edit control is defined to be the text + within the control. This synchronization has the effect of copying whatever text is in the edit control to the data + attribute. Then, when the dialog has terminated, the name the user entered is displayed. (Of course the user may not + have entered her name. What is displayed is whatever the text in the edit control was when the dialog was closed.) + +<programlisting> +<![CDATA[ + + dlg = .NameDlg~new("nameExample.dll", IDD_DIALOG1, , "nameExample.h" ) + + if dlg~initCode == 0 then do + dlg~noAutoDetection + dlg~connectEdit(IDC_EDIT, "NAME") + dlg~name = "Put your name here" + + ret = dlg~execute("SHOWTOP", IDI_DLG_OOREXX) + + if ret == 1 then say "The user's name is:" dlg~name + else say "The user canceled." + end + +return 0 + +::requires "ooDialog.cls" + +::class 'NameDlg' subclass ResDialog + +::method initDialog + self~setDataAttribute("NAME") + +::method ok + self~getDataAttribute("NAME") + self~ok:super + +]]> + </programlisting> + </para> </listitem></varlistentry> </variablelist> -</section> +</section> <!-- End dialog object::connectEdit() --> + <section id="mthConnectListBox"><title>connectListBox</title> <indexterm><primary>connectListBox</primary></indexterm> <indexterm><primary>dialog object</primary><secondary>connectListBox</secondary></indexterm> @@ -1015,9 +1027,9 @@ </programlisting> <para> - The <emphasis role="italic">connectListBox</emphasis> method uses the resource ID to connect a list box in the - underlying dialog to a newly created <link linkend="sctUnderstandingDataAttributes">data attribute</link> in the Rexx - dialog object. + The <emphasis role="italic">connectListBox</emphasis> method uses the resource ID of the control to connect a list box + in the underlying dialog to a newly created <link linkend="sctUnderstandingDataAttributes">data attribute</link> in + the Rexx dialog object. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -1072,8 +1084,10 @@ <para> The attribute has to be synchronized with the list box manually. This can be done globally with the <link linkend="mthSetData">setData</link> and <link linkend="mthGetData">getData</link> methods. For a finer grain - of control use the <link linkend="mthSetDataAttribute">setDataAttribute</link>() or <link - linkend="mthGetDataAttribute">getDataAttribute</link>() methods. + of control use the <link linkend="mthSetListBoxData">setListBoxData</link> or the <link + linkend="mthGetListBoxData">getListBoxData</link>. The <link + linkend="mthSetDataAttribute">setDataAttribute</link>() or <link + linkend="mthGetDataAttribute">getDataAttribute</link>() methods could also be used. </para> <para> The <emphasis role="italic">data</emphasis> of a <emphasis role="bold">single-selection</emphasis> <link @@ -1390,31 +1404,34 @@ </para> </listitem></varlistentry> </variablelist> -</section> +</section> <!-- End dialog object::connectListBox() --> -<section id="mthConnectTreeview"><title>connectTreeView</title> -<indexterm><primary>connectTreeView</primary></indexterm> +<section id="mthConnectListView"><title>connectListView</title> +<indexterm><primary>connectListView</primary></indexterm> +<indexterm><primary>dialog object</primary><secondary>connectListView</secondary></indexterm> <programlisting> <![CDATA[ ->>--connectTreeView(--id--+------------------+--)--------------->< +>>--connectListView(--id--+------------------+--)--------------->< +-,--attributeName-+ ]]> </programlisting> <para> - The <emphasis role="italic">connectTreeView</emphasis> method creates a <link - linkend="sctUnderstandingDataAttributes">data attribute</link> in the Rexx dialog object and connects it to a tree - view control in the underlying dialog using its resource id. + The <emphasis role="italic">connectListView</emphasis> method connects a list view in the underlying dialog, through + its resource ID, to a newly created <link linkend="sctUnderstandingDataAttributes">data attribute</link> in the Rexx + dialog object. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> + <para> + The arguments are: <variablelist> <varlistentry><term>id [required]</term> <listitem> <para> - The resource ID of the tree view control to be connected. Can be numeric or symbolic. + The resource ID of the list view control to be connected. Can be numeric or symbolic. </para> </listitem></varlistentry> <varlistentry><term>attributeName [optional]</term> @@ -1425,6 +1442,7 @@ </para> </listitem></varlistentry> </variablelist> + </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> @@ -1455,17 +1473,17 @@ <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - The attribute has to be synchronized with the tree view control manually. This can be done globally with the <link + The attribute has to be synchronized with the list view control manually. This can be done globally with the <link linkend="mthSetData">setData</link> and <link linkend="mthGetData">getData</link> methods. For a finer grain of control use the <link linkend="mthSetDataAttribute">setDataAttribute</link>() or <link linkend="mthGetDataAttribute">getDataAttribute</link>() methods. </para> <para> - The <emphasis role="italic">data</emphasis> of a <link linkend="clsComboBox">tree view</link> is defined to be the - text of the selected tree view item. + The <emphasis role="italic">data</emphasis> of a <link linkend="clsListView">list view</link> is defined to be a + string containing the blank seperated index(es) of its selected item(s). </para> <para> - The <emphasis role="italic">connectTreeview</emphasis> should only be used when automatic data <link + The <emphasis role="italic">connectCheckBox</emphasis> method should only be used when automatic data <link linkend="paraAutomaticDataDetection">detection</link> is off. </para> </listitem></varlistentry> @@ -1474,66 +1492,201 @@ <para> The <link linkend="exampleConnectEdit">example</link> for the <emphasis role="italic">connectEdit</emphasis> method demonstrates all the pertinent steps to manually connect and use a data attribute for a dialog control. Simply - substitute a tree view for the edit control. + substitute a list view for the edit control. </para> </listitem></varlistentry> </variablelist> -</section> +</section> <!-- End dialog object::connectListView() --> -<section id="mthConnectListView"><title>connectListView</title> -<indexterm><primary>connectListView</primary></indexterm> -<indexterm><primary>dialog object</primary><secondary>connectListView</secondary></indexterm> + +<section id="mthConnectMonthCalendar"><title>connectMonthCalendar</title> +<indexterm><primary>connectMonthCalendar</primary></indexterm> +<indexterm><primary>dialog object</primary><secondary>connectMonthCalendar</secondary></indexterm> <programlisting> <![CDATA[ ->>--connectListView(--id--+------------------+--)--------------->< - +-,--attributeName-+ - +>>--connectMonthCalendar(--id--+------------------+--)---------->< + +-,--attributeName-+ ]]> </programlisting> -<para>The connectListView method creates a new attribute -and connects it to the list-view <emphasis role="italic">id</emphasis>. -The <emphasis role="italic">attributeName</emphasis> is -a string containing the numbers of the selected lines. The numbers are separated -by blanks. Therefore, if value of the attribute after -<link linkend="mthGetData">getData</link> is "3 5 6", the third, -fifth, and sixth items are currently selected, -or will be selected when <link linkend="mthSetData">setData</link> -is executed. For further information, refer to -<link linkend="mthConnectTreeview">connectTreeView</link>.</para> +<para> + The <emphasis role="italic">connectMonthCalendar</emphasis> method connects a month calendar control in the underlying + dialog, through its resource ID, to a newly created <link linkend="sctUnderstandingDataAttributes">data + attribute</link> in the Rexx dialog object. +</para> <variablelist> -<varlistentry><term><emphasis role="bold">Example:</emphasis></term> -<listitem><para>In the following example, the list-view with ID 202 is associated with -the attribute Customers. The first, 14th, and 29th entries in the list are -preselected. -<programlisting> -<![CDATA[ -MyDialog~connectListView(202, "Customers") -MyDialog~Customers="1 14 29" -]]> -</programlisting> -</para></listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The arguments are: + <variablelist> + <varlistentry><term>id [required]</term> + <listitem> + <para> + The resource ID of the month calendar control to be connected. Can be numeric or symbolic. + </para> + </listitem></varlistentry> + <varlistentry><term>attributeName [optional]</term> + <listitem> + <para> + The name of the data attribute to be created. If this argument is omitted or invalid, the attribute name is + generated <link linkend="termConnectAutoNames">automatically</link>. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + The possible return codes are: + <variablelist> + <varlistentry><term>-1</term> + <listitem> + <para> + A symbolic ID was used and it could not be resolved. + </para> + </listitem></varlistentry> + <varlistentry><term>0</term> + <listitem> + <para> + No error. + </para> + </listitem></varlistentry> + <varlistentry><term>1</term> + <listitem> + <para> + The data attribute was created but it was not connected. (The data connection table is full.) + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + The attribute has to be synchronized with the month calendar control manually. This can be done globally with the + <link linkend="mthSetData">setData</link> and <link linkend="mthGetData">getData</link> methods. For a finer grain + of control use the <link linkend="mthSetDataAttribute">setDataAttribute</link>() or <link + linkend="mthGetDataAttribute">getDataAttribute</link>() methods. + </para> + <para> + The <emphasis role="italic">data</emphasis> of a <link linkend="clsMonthCalendar">month caledar</link> is defined + to be a <computeroutput>DateTime</computeroutput> object that specifies the selected date in the month calendar + control. + </para> + <para> + The <emphasis role="italic">connectMonthCalendar</emphasis> method should only be used when automatic data <link + linkend="paraAutomaticDataDetection">detection</link> is off. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + The <link linkend="exampleConnectEdit">example</link> for the <emphasis role="italic">connectEdit</emphasis> method + demonstrates all the pertinent steps to manually connect and use a data attribute for a dialog control. Simply + substitute a month calendar control for the edit control. + </para> + </listitem></varlistentry> </variablelist> -</section> +</section> <!-- End dialog object::connectMonthCalendar() --> -<section id="mthConnectTrackBar"><title>connectTrackBar</title> -<indexterm><primary>connectTrackBar</primary></indexterm> -<indexterm><primary>dialog object</primary><secondary>connectTrackBar</secondary></indexterm> + +<section id="mthConnectRadioButton"><title>connectRadioButton</title> +<indexterm><primary>connectRadioButton</primary></indexterm> +<indexterm><primary>dialog object</primary><secondary>connectRadioButton</secondary></indexterm> <programlisting> <![CDATA[ ->>--connectTrackBar(--id--+------------------+--)--------------->< - +-,--attributeName-+ +>>--connectRadioButton(--id--+-------------------+--)----------->< + +-,--attributeName--+ ]]> </programlisting> -<para>The connectTrackBar method creates a new attribute -and connects it to the track bar <emphasis role="italic">id</emphasis>. -The <emphasis role="italic">attributeName</emphasis> is -the numerical position of the slider. For further information, refer to -<link linkend="mthConnectTreeview">connectTreeView</link>.</para> -</section> +<para> + The <emphasis role="italic">connectRadioButton</emphasis> method uses the resource id of a radio button control to + connect the control in the underlying dialog to a newly created <link + linkend="sctUnderstandingDataAttributes">data attribute</link> in the Rexx dialog object. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The arguments are: + <variablelist> + <varlistentry><term>id [required]</term> + <listitem> + <para> + The resource ID of the radio button control to be connected. Can be numeric or symbolic. + </para> + </listitem></varlistentry> + <varlistentry><term>attributeName [optional]</term> + <listitem> + <para> + The name of the data attribute to be created. If this argument is omitted or invalid, the attribute name is + generated <link linkend="termConnectAutoNames">automatically</link>. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + The possible return codes are: + <variablelist> + <varlistentry><term>-1</term> + <listitem> + <para> + A symbolic ID was used and it could not be resolved. + </para> + </listitem></varlistentry> + <varlistentry><term>0</term> + <listitem> + <para> + No error. + </para> + </listitem></varlistentry> + <varlistentry><term>1</term> + <listitem> + <para> + The data attribute was created but it was not connected. (The data connection table is full.) + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + The attribute has to be synchronized with the radio button control manually. This can be done globally with the + <link linkend="mthSetData">setData</link> and <link linkend="mthGetData">getData</link> methods. For a finer grain + of control use the <link linkend="mthSetRadioButtonData">setRadioButtonData</link> or <link + linkend="mthGetRadioButtonData">getRadioButtonData</link> methods. The <link + linkend="mthSetDataAttribute">setDataAttribute</link>() or <link + linkend="mthGetDataAttribute">getDataAttribute</link>() methods can also be used. + </para> + <para> + The <emphasis role="italic">data</emphasis> of a <link linkend="clsRadioButton">radio button</link> is defined to + be the its check state. This is 0 for not checked and 1 for checked. + </para> + <para> + The <emphasis role="italic">connectRadioButton</emphasis> method should only be used when automatic data <link + linkend="paraAutomaticDataDetection">detection</link> is off. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + The <link linkend="exampleConnectEdit">example</link> for the <emphasis role="italic">connectEdit</emphasis> method + demonstrates all the pertinent steps to manually connect and use a data attribute for a dialog control. Simply + substitute a radio button control for the edit control. + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End dialog object::connectRadioButton() --> + <section id="mthConnectTab"><title>connectTab</title> <indexterm><primary>connectTab</primary></indexterm> <indexterm><primary>dialog object</primary><secondary>connectTab</secondary></indexterm> @@ -1545,162 +1698,441 @@ ]]> </programlisting> -<para>The connectTab method creates a new attribute -and connects it to the tab control <emphasis role="italic">id</emphasis>. -The <emphasis role="italic">attributeName</emphasis> is -the text of the active tab. For further information, refer to -<link linkend="mthConnectTreeview">connectTreeView</link>.</para> -</section> - -<section id="mthConnectDateTimePicker"><title>connectDateTimePicker</title> -<indexterm><primary>connectDateTimePicker</primary></indexterm> -<indexterm><primary>dialog object</primary><secondary>connectDateTimePicker</secondary></indexterm> -<programlisting> -<![CDATA[ ->>--connectDateTimePicker(--id--+------------------+--)--------->< - +-,--attributeName-+ -]]> -</programlisting> - <para> - xx + The <emphasis role="italic">connectTab</emphasis> method uses the resource id of a tab control to connect the control + in the underlying dialog to a newly created <link linkend="sctUnderstandingDataAttributes">data attribute</link> in + the Rexx dialog object. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - xx + The arguments are: <variablelist> - <varlistentry><term>TERM</term> + <varlistentry><term>id [required]</term> <listitem> <para> - xx + The resource ID of the tab control to be connected. Can be numeric or symbolic. </para> </listitem></varlistentry> + <varlistentry><term>attributeName [optional]</term> + <listitem> + <para> + The name of the data attribute to be created. If this argument is omitted or invalid, the attribute name is + generated <link linkend="termConnectAutoNames">automatically</link>. + </para> + </listitem></varlistentry> </variablelist> </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + The possible return codes are: + <variablelist> + <varlistentry><term>-1</term> + <listitem> + <para> + A symbolic ID was used and it could not be resolved. + </para> + </listitem></varlistentry> + <varlistentry><term>0</term> + <listitem> + <para> + No error. + </para> + </listitem></varlistentry> + <varlistentry><term>1</term> + <listitem> + <para> + The data attribute was created but it was not connected. (The data connection table is full.) + </para> + </listitem></varlistentry> + </variablelist> </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + The attribute has to be synchronized with the tab control manually. This can be done globally with the + <link linkend="mthSetData">setData</link> and <link linkend="mthGetData">getData</link> methods. For a finer grain + of control use the <link linkend="mthSetDataAttribute">setDataAttribute</link>() or <link + linkend="mthGetDataAttribute">getDataAttribute</link>() methods. + </para> + <para> + The <emphasis role="italic">data</emphasis> of a <link linkend="clsTab">tab</link> control is defined to the text + of its currently selected tab. + </para> + <para> + The <emphasis role="italic">connectTab</emphasis> method should only be used when automatic data <link + linkend="paraAutomaticDataDetection">detection</link> is off. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - Additional comments. + The <link linkend="exampleConnectEdit">example</link> for the <emphasis role="italic">connectEdit</emphasis> method + demonstrates all the pertinent steps to manually connect and use a data attribute for a dialog control. Simply + substitute a tab control for the edit control. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details</emphasis></term> +</variablelist> +</section> <!-- End dialog object::connectTab() --> + + +<section id="mthConnectTrackBar"><title>connectTrackBar</title> +<indexterm><primary>connectTrackBar</primary></indexterm> +<indexterm><primary>dialog object</primary><secondary>connectTrackBar</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--connectTrackBar(--id--+------------------+--)--------------->< + +-,--attributeName-+ + +]]> +</programlisting> + +<para> + The <emphasis role="italic">connectTrackBar</emphasis> method uses the resource id of a trackbar control to connect + the control in the underlying dialog to a newly created <link linkend="sctUnderstandingDataAttributes">data + attribute</link> in the Rexx dialog object. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - Raises syntax errors when incorrect arguments are detected. + The arguments are: + <variablelist> + <varlistentry><term>id [required]</term> + <listitem> + <para> + The resource ID of the trackbar control to be connected. Can be numeric or symbolic. + </para> + </listitem></varlistentry> + <varlistentry><term>attributeName [optional]</term> + <listitem> + <para> + The name of the data attribute to be created. If this argument is omitted or invalid, the attribute name is + generated <link linkend="termConnectAutoNames">automatically</link>. + </para> + </listitem></varlistentry> + </variablelist> </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. + The possible return codes are: + <variablelist> + <varlistentry><term>-1</term> + <listitem> + <para> + A symbolic ID was used and it could not be resolved. + </para> + </listitem></varlistentry> + <varlistentry><term>0</term> + <listitem> + <para> + No error. + </para> + </listitem></varlistentry> + <varlistentry><term>1</term> + <listitem> + <para> + The data attribute was created but it was not connected. (The data connection table is full.) + </para> + </listitem></varlistentry> + </variablelist> </para> </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + The attribute has to be synchronized with the trackbar control manually. This can be done globally with the <link + linkend="mthSetData">setData</link> and <link linkend="mthGetData">getData</link> methods. For a finer grain of + control use the <link linkend="mthSetDataAttribute">setDataAttribute</link>() or <link + linkend="mthGetDataAttribute">getDataAttribute</link>() methods. + </para> + <para> + The <emphasis role="italic">data</emphasis> of a <link linkend="clsTab">trackbar</link> control is defined to be + the current logical position of the slider in the trackbar. + </para> + <para> + The <emphasis role="italic">connectTab</emphasis> method should only be used when automatic data <link + linkend="paraAutomaticDataDetection">detection</link> is off. + </para> + </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + The <link linkend="exampleConnectEdit">example</link> for the <emphasis role="italic">connectEdit</emphasis> method + demonstrates all the pertinent steps to manually connect and use a data attribute for a dialog control. Simply + substitute a trackbar control for the edit control. + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End dialog object::connectTrackBar() --> + + +<section id="mthConnectTreeview"><title>connectTreeView</title> +<indexterm><primary>connectTreeView</primary></indexterm> <programlisting> <![CDATA[ +>>--connectTreeView(--id--+------------------+--)--------------->< + +-,--attributeName-+ ]]> </programlisting> + +<para> + The <emphasis role="italic">connectTreeView</emphasis> method creates a <link + linkend="sctUnderstandingDataAttributes">data attribute</link> in the Rexx dialog object and connects it to a tree + view control in the underlying dialog using its resource id. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <variablelist> + <varlistentry><term>id [required]</term> + <listitem> + <para> + The resource ID of the tree view control to be connected. Can be numeric or symbolic. + </para> + </listitem></varlistentry> + <varlistentry><term>attributeName [optional]</term> + <listitem> + <para> + The name of the data attribute to be created. If this argument is omitted or invalid, the attribute name is + generated <link linkend="termConnectAutoNames">automatically</link>. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + The possible return codes are: + <variablelist> + <varlistentry><term>-1</term> + <listitem> + <para> + A symbolic ID was used and it could not be resolved. + </para> + </listitem></varlistentry> + <varlistentry><term>0</term> + <listitem> + <para> + No error. + </para> + </listitem></varlistentry> + <varlistentry><term>1</term> + <listitem> + <para> + The data attribute was created but it was not connected. (The data connection table is full.) + </para> + </listitem></varlistentry> + </variablelist> </para> </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + The attribute has to be synchronized with the tree view control manually. This can be done globally with the <link + linkend="mthSetData">setData</link> and <link linkend="mthGetData">getData</link> methods. For a finer grain of + control use the <link linkend="mthSetDataAttribute">setDataAttribute</link>() or <link + linkend="mthGetDataAttribute">getDataAttribute</link>() methods. + </para> + <para> + The <emphasis role="italic">data</emphasis> of a <link linkend="clsTreeView">tree view</link> is defined to be the + text of the selected tree view item. + </para> + <para> + The <emphasis role="italic">connectTreeview</emphasis> should only be used when automatic data <link + linkend="paraAutomaticDataDetection">detection</link> is off. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + The <link linkend="exampleConnectEdit">example</link> for the <emphasis role="italic">connectEdit</emphasis> method + demonstrates all the pertinent steps to manually connect and use a data attribute for a dialog control. Simply + substitute a tree view for the edit control. + </para> + </listitem></varlistentry> </variablelist> -</section> <!-- End dialog object::connectDateTimePicker() --> +</section> <!-- End dialog object::connectTreeView() --> -<section id="mthConnectMonthCalendar"><title>connectMonthCalendar</title> -<indexterm><primary>connectMonthCalendar</primary></indexterm> -<indexterm><primary>dialog object</primary><secondary>connectMonthCalendar</secondary></indexterm> + +<section id="mthConnectUpDown"><title>connectUpDown</title> +<indexterm><primary>connectUpDown</primary></indexterm> +<indexterm><primary>dialog object</primary><secondary>connectUpDown</secondary></indexterm> <programlisting> <![CDATA[ ->>--connectMonthCalendar(--id--+------------------+--)---------->< - +-,--attributeName-+ +>>--connectUpDown(--id--+------------------+--)-->< + +-,--attributeName-+ ]]> </programlisting> <para> - xx + The <emphasis role="italic">connectUpDown</emphasis> method connects an up down control in the underlying dialog, + through its resource ID, to a newly created <link linkend="sctUnderstandingDataAttributes">data attribute</link> in + the Rexx dialog object. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - xx + The arguments are: <variablelist> - <varlistentry><term>TERM</term> + <varlistentry><term>id [required]</term> <listitem> <para> - xx + The resource ID of the up down control to be connected. Can be numeric or symbolic. </para> </listitem></varlistentry> + <varlistentry><term>attributeName [optional]</term> + <listitem> + <para> + The name of the data attribute to be created. If this argument is omitted or invalid, the attribute name is + generated <link linkend="termConnectAutoNames">automatically</link>. + </para> + </listitem></varlistentry> </variablelist> </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + The possible return codes are: + <variablelist> + <varlistentry><term>-1</term> + <listitem> + <para> + A symbolic ID was used and it could not be resolved. + </para> + </listitem></varlistentry> + <varlistentry><term>0</term> + <listitem> + <para> + No error. + </para> + </listitem></varlistentry> + <varlistentry><term>1</term> + <listitem> + <para> + The data attribute was created but it was not connected. (The data connection table is full.) + </para> + </listitem></varlistentry> + </variablelist> </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + The attribute has to be synchronized with the up down control manually. This can be done globally with the + <link linkend="mthSetData">setData</link> and <link linkend="mthGetData">getData</link> methods. For a finer grain + of control use the <link linkend="mthSetDataAttribute">setDataAttribute</link>() or <link + linkend="mthGetDataAttribute">getDataAttribute</link>() methods. + </para> + <para> + The <emphasis role="italic">data</emphasis> of a <link linkend="clsUpDown">up down</link> control is defined to be + the value of its current position. + </para> + <para> + The <emphasis role="italic">connectUpDown</emphasis> method should only be used when automatic data <link + linkend="paraAutomaticDataDetection">detection</link> is off. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - Additional comments. + The <link linkend="exampleConnectEdit">example</link> for the <emphasis role="italic">connectEdit</emphasis> method + demonstrates all the pertinent steps to manually connect and use a data attribute for a dialog control. Simply + substitute an up down control for the edit control. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details</emphasis></term> +</variablelist> +</section> <!-- End dialog object::connectUpDown() --> + +</section> <!-- End Connect Attribute Methods Section --> + + +<section id="mthGetCheckBoxData"><title>getCheckBoxData</title> +<indexterm><primary>getCheckBoxData</primary></indexterm> +<indexterm><primary>dialog object</primary><secondary>getCheckBoxData</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--getCheckBoxData(--id--)---------------------->< + +]]> +</programlisting> + +<para> + The <emphasis role="italic">getCheckBoxData</emphasis> method gets the <link + linkend="sctUnderstandingDataAttributes">data</link> of a a check box. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - Raises syntax errors when incorrect arguments are detected. + The only argument is: + <variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The resource ID of the check box. May be numeric or symbolic. + </para> + </listitem></varlistentry> + </variablelist> </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. + The <emphasis role="italic">data</emphasis> of a check box is considered to be whether it is checked or not. If the + check box is checked the return is 1 and if unchecked the return is 0. </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - This example ... -<programlisting> -<![CDATA[ - -]]> -</programlisting> + The check box <emphasis role="bold">should</emphasis> have been previously connected to a data attribute. If it has + not, or if the resource ID is not the ID of a check box, the results are unpredictable. </para> </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + This method can only be invoked after the underlying Windows dialog has been created. A syntax condition is raised if + the underlying dialog does not exist. + </para> + </listitem></varlistentry> </variablelist> -</section> <!-- End dialog object::connectMonthCalendar() --> +</section> -<section id="mthUonnectUpDown"><title>connectUpDown</title> -<indexterm><primary>connectUpDown</primary></indexterm> -<indexterm><primary>dialog object</primary><secondary>connectUpDown</secondary></indexterm> + +<section id="mthGetComboBoxData"><title>getComboBoxData</title> +<indexterm><primary>getComboBoxData</primary></indexterm> <programlisting> <![CDATA[ ->>--connectUpDown(--id--+------------------+--)-->< - +-,--attributeName-+ +>>--getComboBoxData(--id--)---------------------->< + ]]> </programlisting> <para> - xx + The <emphasis role="italic">getComboBoxData</emphasis> method gets the <link + linkend="sctUnderstandingDataAttributes">data</link> of a combo box. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - xx + The only argument is: <variablelist> - <varlistentry><term>TERM</term> + <varlistentry><term>id [required]</term> <listitem> <para> - xx + The resource ID of the combo box. May be numeric or symbolic. </para> </listitem></varlistentry> </variablelist> @@ -1709,39 +2141,111 @@ <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + The <emphasis role="italic">data</emphasis> of a combo box is considered to be the text of the selection field in + the <link linkend="clsComboBox">combo box</link>. The current text in the selection field is returned, which may be + the empty string if there is no text in the selection field. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + The combo box <emphasis role="bold">should</emphasis> have been previously connected to a data attribute. If it has + n0t, or if the resource ID is not the ID of a combo box, the results are unpredictable. </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details</emphasis></term> - <listitem> <para> - Raises syntax errors when incorrect arguments are detected. + For drop down list combo boxes, the text in the selection field is the same as the text of the current selection. + The text returned may still be the empty string if there is no current selection. </para> <para> - Sets the <link linkend="dotSystemErrorCode">.SystemErrorCode</link> variable. + However, for simple and drop down combo boxes things are not so simple. The text in the selection field could be + text the user typed in and there may be no current selection. Or, for these types of combo boxes, there might be a + current selection, but the user may have edited the text in the selection field so that it no longer matches the + text of the current selection. </para> + <para> + To get the index of the current selection, use the <link linkend="h000344">GetCurrentComboIndex</link> method. + </para> </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> <listitem> <para> - This example ... + This method can only be invoked after the underlying Windows dialog has been created. A syntax condition is raised if + the underlying dialog does not exist. + </para> + </listitem></varlistentry> +</variablelist> +</section> + +<section id="mthGetControlData"><title>getControlData</title> +<indexterm><primary>getControlData</primary></indexterm> +<indexterm><primary>dialog object</primary><secondary>getControlData</secondary></indexterm> <programlisting> <![CDATA[ +>>--getControlData(--id--)----------------------->< ]]> </programlisting> + +<para> + The <emphasis role="italic">getControlData</emphasi... [truncated message content] |