Menu
▾
▴
[Oorexx-svn] SF.net SVN: oorexx-code-0:[9048] docs/trunk/oodialog/en-US
|
From: <mie...@us...> - 2013-02-28 00:58:54
|
Revision: 9048
http://sourceforge.net/p/oorexx/code-0/9048
Author: miesfeld
Date: 2013-02-28 00:58:52 +0000 (Thu, 28 Feb 2013)
Log Message:
-----------
ooDialog doc - incemental update
Modified Paths:
--------------
docs/trunk/oodialog/en-US/resizableDialogs.xml
docs/trunk/oodialog/en-US/userInput.xml
Modified: docs/trunk/oodialog/en-US/resizableDialogs.xml
===================================================================
--- docs/trunk/oodialog/en-US/resizableDialogs.xml 2013-02-28 00:14:43 UTC (rev 9047)
+++ docs/trunk/oodialog/en-US/resizableDialogs.xml 2013-02-28 00:58:52 UTC (rev 9048)
@@ -1648,7 +1648,7 @@
role="italic">pinned</emphasis> to the right edge of the dialog. As the left edge of the dialog is pulled to the left, the
pinned left edge of the list-view is pulled to the left along with it. The right edge of the list-view is pinned to the
right edge of the dialog, so it remains stationary, (the right edge of the dialog is stationary.) As the dialog increases
- in width and the list-view increases in width also.
+ in width, the list-view increases in width also.
</para>
<para>
Every edge of every control in the dialog has a <emphasis role="italic">sizing defintion</emphasis> assigned to it. If the
@@ -1683,8 +1683,8 @@
</listitem>
<listitem>
<para>
- The <emphasis role="italic">edge</emphasis> of the dialog control that is being defined. An edge being defined is specified
- by one of four keywords: LEFT, TOP, RIGHT, and BOTTOM. Case is not significant.
+ The <emphasis role="italic">pinned edge</emphasis> of the dialog control that is being defined. The pinned edge being
+ defined is specified by one of four keywords: LEFT, TOP, RIGHT, and BOTTOM. Case is not significant.
</para>
</listitem>
<listitem>
@@ -1710,9 +1710,42 @@
</itemizedlist>
<variablelist>
- <varlistentry><term><emphasis role="bold">Pinned to edge:</emphasis></term>
+ <varlistentry><term><emphasis role="bold">Pinned edge:</emphasis></term>
<listitem>
<para>
+ The following specifies the meaning of the pinned edge keywords:
+ </para>
+
+ <variablelist>
+ <varlistentry><term>Left:</term>
+ <listitem>
+ <para>
+ This should be self-explanatory, but technically it is the vertical edge of the window with the smallest X co-ordinate.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term>Top:</term>
+ <listitem>
+ <para>
+ This should be self-explanatory, but technically it is the horizontal edge of the window with the smallest Y co-ordinate.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term>Right:</term>
+ <listitem>
+ <para>
+ This should be self-explanatory, but technically it is the vertical edge of the window with the largest X co-ordinate.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term>Bottom:</term>
+ <listitem>
+ <para>
+ This should be self-explanatory, but technically it is the horizontal edge of the window with the largest Y co-ordinate.
+ </para>
+ </listitem></varlistentry>
+ </variablelist>
+ </listitem></varlistentry>
+ <varlistentry id="varPinnedToEdge" xreflabel="pinned to edge"><term><emphasis role="bold">Pinned to edge:</emphasis></term>
+ <listitem>
+ <para>
The following specifies the meaning of the pinned to edge keywords:
</para>
@@ -1720,25 +1753,25 @@
<varlistentry><term>Left:</term>
<listitem>
<para>
- Self-explanatory, but technically it is the vertical edge of the window with the smallest X co-ordinate.
+ This should be self-explanatory, but technically it is the vertical edge of the window with the smallest X co-ordinate.
</para>
</listitem></varlistentry>
<varlistentry><term>Top:</term>
<listitem>
<para>
- Self-explanatory, but technically it is the horizontal edge of the window with the smallest Y co-ordinate.
+ This should be self-explanatory, but technically it is the horizontal edge of the window with the smallest Y co-ordinate.
</para>
</listitem></varlistentry>
<varlistentry><term>Right:</term>
<listitem>
<para>
- Self-explanatory, but technically it is the vertical edge of the window with the largest X co-ordinate.
+ This should be self-explanatory, but technically it is the vertical edge of the window with the largest X co-ordinate.
</para>
</listitem></varlistentry>
<varlistentry><term>Bottom:</term>
<listitem>
<para>
- Self-explanatory, but technically it is the horizontal edge of the window with the largest Y co-ordinate.
+ This should be self-explanatory, but technically it is the horizontal edge of the window with the largest Y co-ordinate.
</para>
</listitem></varlistentry>
<varlistentry><term>XCenter:</term>
@@ -1759,7 +1792,7 @@
</listitem></varlistentry>
</variablelist>
</listitem></varlistentry>
- <varlistentry><term><emphasis role="bold">Pin type:</emphasis></term>
+ <varlistentry id="varPinType" xreflabel="pin type"><term><emphasis role="bold">Pin type:</emphasis></term>
<listitem>
<para>
The following specifies the meaning of the pin type keywords:
@@ -1871,7 +1904,7 @@
</row>
<row>
<entry><xref linkend="atrMinSize"/></entry>
-<entry>Reflects the minimum size the dialog is allowed to resize to. By default, the minimum size for the dialog is set to its initial when the operating system first creates it.</entry>
+<entry>Reflects the minimum size the dialog is allowed to resize to. By default, the minimum size for the dialog is set to its initial size when the operating system first creates it.</entry>
</row>
<row>
<entry align="center"><emphasis role="bold">Instance Methods</emphasis></entry>
@@ -1879,23 +1912,23 @@
</row>
<row>
<entry><xref linkend="mthControlBottom"/></entry>
-<entry>xx</entry>
+<entry>Defines the sizing for the bottom edge of the dialog control specified.</entry>
</row>
<row>
<entry><xref linkend="mthControlLeft"/></entry>
-<entry>xx</entry>
+<entry>Defines the sizing for the left edge of the dialog control specified.</entry>
</row>
<row>
<entry><xref linkend="mthControlRight"/></entry>
-<entry>xx</entry>
+<entry>Defines the sizing for the right edge of the dialog control specified.</entry>
</row>
<row>
<entry><xref linkend="mthControlSizing"/></entry>
-<entry>xx</entry>
+<entry>Defines the sizing for some or all of the edges of the specified dialog control with one method call.</entry>
</row>
<row>
<entry><xref linkend="mthControlTop"/></entry>
-<entry>xx</entry>
+<entry>Defines the sizing for the top edge of the dialog control specified.</entry>
</row>
<row>
<entry><xref linkend="mthDefaultBottom"/></entry>
@@ -1946,9 +1979,9 @@
<indexterm><primary>ResizingAdmin class</primary><secondary>maxSize</secondary></indexterm>
<programlisting>
<![CDATA[
->>--maxSize-----------------------------------------------------><
+>>--maxSize--------------------------------------><
->>--maxSize = sizeObj-------------------------------------------><
+>>--maxSize = sizeObj----------------------------><
]]>
</programlisting>
@@ -1970,7 +2003,7 @@
<para>
Sets the maximum size a dialog can be sized to using a <computeroutput>Size</computeroutput> object. The <emphasis
role="italic">width</emphasis> of the <computeroutput>size</computeroutput> object is the maximum width, in pixels, for
- the dialog and the <emphasis role="italic">height</emphasis> of the <computeroutput>size</computeroutput> object is the
+ the dialog and the <emphasis role="italic">height</emphasis> of the <computeroutput>Size</computeroutput> object is the
maximum height, in pixels for the dialog. By default, the dialog will not have a maximum size restriction.
</para>
</listitem></varlistentry>
@@ -1996,7 +2029,7 @@
<varlistentry><term><emphasis role="bold">Example:</emphasis></term>
<listitem>
<para>
- This example set the maximum size for the resizable dialog based on a proportion of the initial dialog size.
+ This example sets the maximum size for the resizable dialog based on a proportion of the initial dialog size.
<programlisting>
<![CDATA[
@@ -2018,16 +2051,16 @@
<indexterm><primary>ResizingAdmin class</primary><secondary>minSize</secondary></indexterm>
<programlisting>
<![CDATA[
->>--minSize-----------------------------------------------------><
+>>--minSize--------------------------------------><
->>--minSize = sizeObj-------------------------------------------><
+>>--minSize = sizeObj----------------------------><
]]>
</programlisting>
<para>
Reflects the minimum size the dialog is allowed to resize to. By default, the minimum size for the dialog is set to its
- initial when the operating system first creates it.
+ initial size when the operating system first creates it.
</para>
<variablelist>
<varlistentry><term><emphasis role="bold">minSize get:</emphasis></term>
@@ -2042,7 +2075,7 @@
<para>
Set the minimum size the dialog can be sized to using a <computeroutput>Size</computeroutput> object. The <emphasis
role="italic">width</emphasis> of the <computeroutput>size</computeroutput> object is the minimum width, in pixels, for
- the dialog and the <emphasis role="italic">height</emphasis> of the <computeroutput>size</computeroutput> object is the
+ the dialog and the <emphasis role="italic">height</emphasis> of the <computeroutput>Size</computeroutput> object is the
minimum height, in pixels, for the dialog. By default, the dialog will have an initial minimum size restriction set to
the size of the dialog when first created.
</para>
@@ -2092,8 +2125,8 @@
<indexterm><primary>ResizingAdmin class</primary><secondary>controlBottom</secondary></indexterm>
<programlisting>
<![CDATA[
->>--controlBottom(--ctrlID-,-howPinned-,-pinToEdge--+----------------+--)------><
- +-,-pinToWindow--+
+>>--controlBottom(--id--,--howPinned--,--pinToEdge--+------------------+--)----><
+ +--,--pinToWindow--+
]]>
</programlisting>
@@ -2107,24 +2140,46 @@
The arguments are:
</para>
<variablelist>
- <varlistentry><term>TERM</term>
+ <varlistentry><term>id [required]</term>
<listitem>
<para>
- xx
+ The resource ID of the dialog control whose sizing is being defined. May be numeric or <xref linkend="defSymbolicId"/>.
</para>
</listitem></varlistentry>
+ <varlistentry><term>howPinned [required]</term>
+ <listitem>
+ <para>
+ The <xref linkend="varPinType"/> keyword for the sizing definition.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term>pinToEdge [required]</term>
+ <listitem>
+ <para>
+ The <xref linkend="varPinnedToEdge"/> keyword for the sizing definition.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term>pinToWindow [optional]</term>
+ <listitem>
+ <para>
+ The window the bottom edge is being pinned to. By default this is the dialog window. To specify a dialog control window
+ use the resource ID of the control. This may be numeric or <xref linkend="defSymbolicId"/>. The <link
+ linkend="tblResizingAdminMethods">IDC_IDC_DEFAULT_PINTO_WINDOW</link> constant can also be used to explicitly define
+ the pin to window as the dialog window.
+ </para>
+ </listitem></varlistentry>
</variablelist>
</listitem></varlistentry>
<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.
+ When defining the sizing for the bottom edge, the definition <emphasis role="bold">must</emphasis> be correct. If an
+ incorrect definition is detected, a syntax condition is raised.
</para>
</listitem></varlistentry>
<varlistentry><term><emphasis role="bold">Details</emphasis></term>
@@ -2141,10 +2196,12 @@
<varlistentry><term><emphasis role="bold">Example:</emphasis></term>
<listitem>
<para>
- This example ...
+ This example defines the sizing for the bottom edge of a list-view:
<programlisting>
<![CDATA[
+ self~controlBottom(IDC_LV_MAIN, 'STATIONARY', 'BOTTOM')
+
]]>
</programlisting>
</para>
@@ -2157,13 +2214,13 @@
<indexterm><primary>ResizingAdmin class</primary><secondary>controlLeft</secondary></indexterm>
<programlisting>
<![CDATA[
->>--controlLeft(--+--------+--)---------------------------------------------><
- +--type--+
+>>--controlLeft(--id--,--howPinned--,--pinToEdge--+------------------+--)------><
+ +--,--pinToWindow--+
]]>
</programlisting>
<para>
- xx
+ Defines the sizing for the left edge of the dialog control specified.
</para>
<variablelist>
<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term>
@@ -2172,24 +2229,46 @@
The arguments are:
</para>
<variablelist>
- <varlistentry><term>TERM</term>
+ <varlistentry><term>id [required]</term>
<listitem>
<para>
- xx
+ The resource ID of the dialog control whose sizing is being defined. May be numeric or <xref linkend="defSymbolicId"/>.
</para>
</listitem></varlistentry>
+ <varlistentry><term>howPinned [required]</term>
+ <listitem>
+ <para>
+ The <xref linkend="varPinType"/> keyword for the sizing definition.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term>pinToEdge [required]</term>
+ <listitem>
+ <para>
+ The <xref linkend="varPinnedToEdge"/> keyword for the sizing definition.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term>pinToWindow [optional]</term>
+ <listitem>
+ <para>
+ The window the left edge is being pinned to. By default this is the dialog window. To specify a dialog control window
+ use the resource ID of the control. This may be numeric or <xref linkend="defSymbolicId"/>. The <link
+ linkend="tblResizingAdminMethods">IDC_IDC_DEFAULT_PINTO_WINDOW</link> constant can also be used to explicitly define
+ the pin to window as the dialog window.
+ </para>
+ </listitem></varlistentry>
</variablelist>
</listitem></varlistentry>
<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.
+ When defining the sizing for the left edge, the definition <emphasis role="bold">must</emphasis> be correct. If an
+ incorrect definition is detected, a syntax condition is raised.
</para>
</listitem></varlistentry>
<varlistentry><term><emphasis role="bold">Details</emphasis></term>
@@ -2206,10 +2285,12 @@
<varlistentry><term><emphasis role="bold">Example:</emphasis></term>
<listitem>
<para>
- This example ...
+ This example defines the sizing for the left edge of a list-view:
<programlisting>
<![CDATA[
+ self~controlLeft(IDC_LV_MAIN, 'STATIONARY', 'LEFT')
+
]]>
</programlisting>
</para>
@@ -2222,13 +2303,13 @@
<indexterm><primary>ResizingAdmin class</primary><secondary>controlRight</secondary></indexterm>
<programlisting>
<![CDATA[
->>--controlRight(--+--------+--)---------------------------------------------><
- +--type--+
+>>--controlRight(--id--,--howPinned--,--pinToEdge--+------------------+--)-----><
+ +--,--pinToWindow--+
]]>
</programlisting>
<para>
- xx
+ Defines the sizing for the right edge of the dialog control specified.
</para>
<variablelist>
<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term>
@@ -2237,24 +2318,46 @@
The arguments are:
</para>
<variablelist>
- <varlistentry><term>TERM</term>
+ <varlistentry><term>id [required]</term>
<listitem>
<para>
- xx
+ The resource ID of the dialog control whose sizing is being defined. May be numeric or <xref linkend="defSymbolicId"/>.
</para>
</listitem></varlistentry>
+ <varlistentry><term>howPinned [required]</term>
+ <listitem>
+ <para>
+ The <xref linkend="varPinType"/> keyword for the sizing definition.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term>pinToEdge [required]</term>
+ <listitem>
+ <para>
+ The <xref linkend="varPinnedToEdge"/> keyword for the sizing definition.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term>pinToWindow [optional]</term>
+ <listitem>
+ <para>
+ The window the right edge is being pinned to. By default this is the dialog window. To specify a dialog control window
+ use the resource ID of the control. This may be numeric or <xref linkend="defSymbolicId"/>. The <link
+ linkend="tblResizingAdminMethods">IDC_IDC_DEFAULT_PINTO_WINDOW</link> constant can also be used to explicitly define
+ the pin to window as the dialog window.
+ </para>
+ </listitem></varlistentry>
</variablelist>
</listitem></varlistentry>
<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.
+ When defining the sizing for the right edge, the definition <emphasis role="bold">must</emphasis> be correct. If an
+ incorrect definition is detected, a syntax condition is raised.
</para>
</listitem></varlistentry>
<varlistentry><term><emphasis role="bold">Details</emphasis></term>
@@ -2271,10 +2374,13 @@
<varlistentry><term><emphasis role="bold">Example:</emphasis></term>
<listitem>
<para>
- This example ...
+ This example defines the sizing for the right edge of a list-view. To be sure the code is clear to anyone looking at it,
+ the programmer decided to explicitly name the window the right edge is pinned to:
<programlisting>
<![CDATA[
+ self~controlRight(IDC_LV_MAIN, 'STATIONARY', 'RIGHT', self~IDC_IDC_DEFAULT_PINTO_WINDOW)
+
]]>
</programlisting>
</para>
@@ -2287,13 +2393,13 @@
<indexterm><primary>ResizingAdmin class</primary><secondary>controlSizing</secondary></indexterm>
<programlisting>
<![CDATA[
->>--controlSizing(--+--------+--)---------------------------------------------><
- +--type--+
+>>--controlSizing(--id--+--------- +--+--------+--+---------+--+-----------+--)-----><
+ +-,-right--+ +-,-top--+ +-,-left--+ +-,-bottom--+
]]>
</programlisting>
<para>
- xx
+ Defines the sizing for some or all of the edges of the specified dialog control with one method call.
</para>
<variablelist>
<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term>
@@ -2302,25 +2408,88 @@
The arguments are:
</para>
<variablelist>
- <varlistentry><term>TERM</term>
+ <varlistentry><term>id [required]</term>
<listitem>
<para>
- xx
+ The resource ID of the dialog control whose sizing is being defined. May be numeric or <xref linkend="defSymbolicId"/>.
</para>
</listitem></varlistentry>
+ <varlistentry><term>right [opitonal]</term>
+ <listitem>
+ <para>
+ An array whose indexes define the sizing for the right edge of the control. If this argument is omitted, the current
+ default <link linkend="mthDefaultRight">right</link> sizing definition is used. See the remarks section for the details
+ on constructing the array and its indexes.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term>top [opitonal]</term>
+ <listitem>
+ <para>
+ An array whose indexes define the sizing for the top edge of the control. If this argument is omitted, the current
+ default <link linkend="mthDefaultTop">top</link> sizing definition is used. See the remarks section for the details
+ on constructing the array and its indexes.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term>left [opitonal]</term>
+ <listitem>
+ <para>
+ An array whose indexes define the sizing for the left edge of the control. If this argument is omitted, the current
+ default <link linkend="mthDefaultLeft">left</link> sizing definition is used. See the remarks section for the details
+ on constructing the array and its indexes.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term>bottom [opitonal]</term>
+ <listitem>
+ <para>
+ An array whose indexes define the sizing for the bottom edge of the control. If this argument is omitted, the current
+ default <link linkend="mthDefaultBottom">bottom</link> sizing definition is used. See the remarks section for the
+ details on constructing the array and its indexes.
+ </para>
+ </listitem></varlistentry>
</variablelist>
</listitem></varlistentry>
<varlistentry><term><emphasis role="bold">Return value:</emphasis></term>
<listitem>
<para>
- xx
+ Returns 0 on success, 1 on error.
</para>
</listitem></varlistentry>
<varlistentry><term><emphasis role="bold">Remarks:</emphasis></term>
<listitem>
<para>
- Additional comments.
+ The <emphasis role="italic">right</emphasis>, <emphasis role="italic">top</emphasis>, etc., arguments must be an array.
+ Each array must contain index 1 and index 2. Index 3 is optional. The arrays are formed are as follows:
</para>
+ <variablelist>
+ <varlistentry><term>Index 1 [required]</term>
+ <listitem>
+ <para>
+ The <xref linkend="varPinType"/> keyword for the sizing definition of the edge.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term>Index 2 [required]</term>
+ <listitem>
+ <para>
+ The <xref linkend="varPinnedToEdge"/> keyword for the sizing definition of the edge.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term>Index 3 [optional]</term>
+ <listitem>
+ <para>
+ The window the edge is being pinned to. By default this is the dialog window. To specify a dialog control window use
+ the resource ID of the control. This may be numeric or <xref linkend="defSymbolicId"/>. The <link
+ linkend="tblResizingAdminMethods">IDC_IDC_DEFAULT_PINTO_WINDOW</link> constant can also be used to explicitly define
+ the pin to window as the dialog window.
+ </para>
+ </listitem></varlistentry>
+ </variablelist>
+ <para>
+ For any of the optional edge sizing definition arguments that are omitted, a sizing edge defintion is constructed using
+ the default sizing in effect at the time. Not that the default sizing can be changed using the <xref
+ linkend="mthDefaultLeft"/>, <xref linkend="mthDefaultTop"/>, etc., methods. Changing the default sizing has no effect on
+ the sizing defintion for any control that has already been added to the sizing table. It only effects sizign added after
+ the default has been changed.
+ </para>
</listitem></varlistentry>
<varlistentry><term><emphasis role="bold">Details</emphasis></term>
<listitem>
@@ -2336,10 +2505,18 @@
<varlistentry><term><emphasis role="bold">Example:</emphasis></term>
<listitem>
<para>
- This example ...
+ This example defines the sizing for all edges of an edit control using the <emphasis
+ role="italic">controlSizing</emphasis> method. Note that there are any number of ways the Rexx code could be formatted
+ here. The format shown is merely one way, it is not required:
<programlisting>
<![CDATA[
+ self~controlSizing(IDC_EDIT_NAMES, -
+ .array~of('STATIONARY', 'LEFT', IDC_ST_NAMES), -
+ .array~of('STATIONARY', 'TOP', IDC_GB_TEST), -
+ .array~of('STATIONARY', 'LEFT', IDC_ST_LABELS), -
+ .array~of('MYTOP', 'TOP') -
+ )
]]>
</programlisting>
</para>
@@ -2352,13 +2529,13 @@
<indexterm><primary>ResizingAdmin class</primary><secondary>controlTop</secondary></indexterm>
<programlisting>
<![CDATA[
->>--controlTop(--+--------+--)---------------------------------------------><
- +--type--+
+>>--controlTop(--id--,--howPinned--,--pinToEdge--+------------------+--)-------><
+ +--,--pinToWindow--+
]]>
</programlisting>
<para>
- xx
+ Defines the sizing for the bottom edge of the dialog control specified.
</para>
<variablelist>
<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term>
@@ -2367,24 +2544,46 @@
The arguments are:
</para>
<variablelist>
- <varlistentry><term>TERM</term>
+ <varlistentry><term>id [required]</term>
<listitem>
<para>
- xx
+ The resource ID of the dialog control whose sizing is being defined. May be numeric or <xref linkend="defSymbolicId"/>.
</para>
</listitem></varlistentry>
+ <varlistentry><term>howPinned [required]</term>
+ <listitem>
+ <para>
+ The <xref linkend="varPinType"/> keyword for the sizing definition.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term>pinToEdge [required]</term>
+ <listitem>
+ <para>
+ The <xref linkend="varPinnedToEdge"/> keyword for the sizing definition.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term>pinToWindow [optional]</term>
+ <listitem>
+ <para>
+ The window the top edge is being pinned to. By default this is the dialog window. To specify a dialog control window
+ use the resource ID of the control. This may be numeric or <xref linkend="defSymbolicId"/>. The <link
+ linkend="tblResizingAdminMethods">IDC_IDC_DEFAULT_PINTO_WINDOW</link> constant can also be used to explicitly define
+ the pin to window as the dialog window.
+ </para>
+ </listitem></varlistentry>
</variablelist>
</listitem></varlistentry>
<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.
+ When defining the sizing for the top edge, the definition <emphasis role="bold">must</emphasis> be correct. If an
+ incorrect definition is detected, a syntax condition is raised.
</para>
</listitem></varlistentry>
<varlistentry><term><emphasis role="bold">Details</emphasis></term>
@@ -2401,10 +2600,12 @@
<varlistentry><term><emphasis role="bold">Example:</emphasis></term>
<listitem>
<para>
- This example ...
+ This example defines the sizing for the top edge of a list-view:
<programlisting>
<![CDATA[
+ self~controlTop(IDC_LV_MAIN,'STATIONARY', 'TOP')
+
]]>
</programlisting>
</para>
@@ -2418,13 +2619,14 @@
<indexterm><primary>ResizingAdmin class</primary><secondary>defaultBottom</secondary></indexterm>
<programlisting>
<![CDATA[
->>--defaultBottom(--+--------+--)---------------------------------------------><
- +--type--+
+>>--defaultBottom(----howPinned--,--pinToEdge--)----------------><
]]>
</programlisting>
<para>
- xx
+ Changes the default sizing policy for the bottom edge of dialog controls. Before the underlying Windows dialog starts
+ executing, every edge of every dialog control in the dialog is assigned a sizing definition. Every edge that the
+ application has not explicitly defined a sizing for is assigned the default sizing definition for that edge.
</para>
<variablelist>
<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term>
@@ -2433,18 +2635,24 @@
The arguments are:
</para>
<variablelist>
- <varlistentry><term>TERM</term>
+ <varlistentry><term>howPinned [required]</term>
<listitem>
<para>
- xx
+ The <xref linkend="varPinType"/> keyword for the sizing definition.
</para>
</listitem></varlistentry>
+ <varlistentry><term>pinToEdge [required]</term>
+ <listitem>
+ <para>
+ The <xref linkend="varPinnedToEdge"/> keyword for the sizing definition.
+ </para>
+ </listitem></varlistentry>
</variablelist>
</listitem></varlistentry>
<varlistentry><term><emphasis role="bold">Return value:</emphasis></term>
<listitem>
<para>
- xx
+ Returns 0 on success, 1 on error.
</para>
</listitem></varlistentry>
<varlistentry><term><emphasis role="bold">Remarks:</emphasis></term>
@@ -2483,13 +2691,14 @@
<indexterm><primary>Resizing class</primary><secondary>defaultLeft</secondary></indexterm>
<programlisting>
<![CDATA[
->>--defaultLeft(--+--------+--)---------------------------------------------><
- +--type--+
+>>--defaultLeft(----howPinned--,--pinToEdge--)---><
]]>
</programlisting>
<para>
- xx
+ Changes the default sizing policy for the left edge of dialog controls. Before the underlying Windows dialog starts
+ executing, every edge of every dialog control in the dialog is assigned a sizing definition. Every edge that the
+ application has not explicitly defined a sizing for is assigned the default sizing definition for that edge.
</para>
<variablelist>
<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term>
@@ -2548,13 +2757,14 @@
<indexterm><primary>ResizingAdmin class</primary><secondary>defaultRight</secondary></indexterm>
<programlisting>
<![CDATA[
->>--defaultRight(--+--------+--)---------------------------------------------><
- +--type--+
+>>--defaultRight(----howPinned--,--pinToEdge--)--><
]]>
</programlisting>
<para>
- xx
+ Changes the default sizing policy for the right edge of dialog controls. Before the underlying Windows dialog starts
+ executing, every edge of every dialog control in the dialog is assigned a sizing definition. Every edge that the
+ application has not explicitly defined a sizing for is assigned the default sizing definition for that edge.
</para>
<variablelist>
<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term>
@@ -2680,13 +2890,14 @@
<indexterm><primary>ResizingAdmin class</primary><secondary>defaultTop</secondary></indexterm>
<programlisting>
<![CDATA[
->>--defaultTop(--+--------+--)---------------------------------------------><
- +--type--+
+>>--defaultTop(----howPinned--,--pinToEdge--)----><
]]>
</programlisting>
<para>
- xx
+ Changes the default sizing policy for the top edge of dialog controls. Before the underlying Windows dialog starts
+ executing, every edge of every dialog control in the dialog is assigned a sizing definition. Every edge that the
+ application has not explicitly defined a sizing for is assigned the default sizing definition for that edge.
</para>
<variablelist>
<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term>
Modified: docs/trunk/oodialog/en-US/userInput.xml
===================================================================
--- docs/trunk/oodialog/en-US/userInput.xml 2013-02-28 00:14:43 UTC (rev 9047)
+++ docs/trunk/oodialog/en-US/userInput.xml 2013-02-28 00:58:52 UTC (rev 9048)
@@ -353,10 +353,9 @@
<para>
The Windows Shell identifies objects in the Shell using a device called an item ID list. Files, folders, printers,
remote computers all have an item ID list that is used to uniquely identify them to the Shell. The ooDialog programmer
- does not really need to know about the details of these item ID lists. Although technically incorrect, the programmer can
- just think of them as <link linkend="defHandle">handles</link>. However, it is difficult to document the
- <computeroutput>BrowseForFolder</computeroutput> class without making some reference to an item ID list. For that
- purpose, this brief explanation is included.
+ does not really need to know about the details of these item ID lists. However, it is difficult to document the
+ <computeroutput>BrowseForFolder</computeroutput> class without making references to an item ID list. Although technically
+ incorrect, the programmer can just think of them as <link linkend="defHandle">handles</link>.
</para>
</listitem></varlistentry>
</variablelist>
@@ -810,7 +809,7 @@
</row>
<row>
<entry><xref linkend="mthGetDisplayName"/> </entry>
-<entry>Returns the display name relative to the file system path</entry>
+<entry>Returns the display name for an item <link linkend="varItemIDList">ID</link> list.</entry>
</row>
<row>
<entry><xref linkend="mthGetFolder"/> </entry>
@@ -1849,7 +1848,7 @@
exactly one of the following keyword, case is not significant:
</para>
<para>
- <simplelist type='vert' columns='3'>
+ <simplelist type='vert' columns='2'>
<member>DESKTOPABSOLUTEEDITING </member>
<member>DESKTOPABSOLUTEPARSING </member>
<member>FILESYSPATH </member>
@@ -2136,7 +2135,7 @@
combination allows the browsing of every folder in the shell. In the first invocation of <emphasis
role="italic">getItemIDList</emphasis>, note the use of the <emphasis role="italic">reuse</emphasis> arg. The prevents
the COM library from being released. Then in the last invocation of <emphasis role="italic">getFolder</emphasis>, the
- <emphasis role="italic">reuse</emphasis> arg is not used, and the ooDialog framework takes car of releasing the COM
+ <emphasis role="italic">reuse</emphasis> arg is not used, and the ooDialog framework takes care of releasing the COM
library. However, if the user cancels the first showing of the dialog, the application handles releasing COM before it
returns:
<programlisting>
@@ -2220,8 +2219,29 @@
<varlistentry><term><emphasis role="bold">Remarks:</emphasis></term>
<listitem>
<para>
- Additional comments.
+ When the browse for folder dialog is first instantiated, the ooDialog framework initializes the COM library on the thread
+ that is executing. If that same object is used on another thread than the initial thread, the methods of the object may
+ fail unless the COM library is initialized on the other thread. The <emphasis role="italic">initCOM</emphasis> method is
+ provided to perform that initialization.
</para>
+ <para>
+ For each invocation of <emphasis role="italic">initCOM</emphasis> that returns true, a matching call to <xref
+ linkend="mthReleaseCOM"/> must be made on the same thread. Note that the <xref linkend="mthGetFolder"/> and <xref
+ linkend="mthGetItemIDList"/> methods release the COM library on the thread they are executing in when the <emphasis
+ role="italic">reuse</emphasis> arguemnt is false. Therefore, if <emphasis role="italic">initCOM</emphasis> is invoked on
+ thread xx, the matching release COM requirement can be fulfilled by invoking <emphasis role="italic">getFolder</emphasis>
+ with the <emphasis role="italic">reuse</emphasis> argument set to false.
+ </para>
+ <para>
+ If <emphasis role="italic">initCOM</emphasis> returns false, then there is no need to invoke <emphasis
+ role="italic">releaseCOM</emphasis>. Indeed, invoking <emphasis role="italic">releaseCOM</emphasis> will be a mistake as
+ this will cause the matching <emphasis role="italic">initCOM</emphasis> / <emphasis role="italic">releaseCOM</emphasis>
+ calls to become unbalanced. When <emphasis role="italic">initCom</emphasis> returns false, it can be for two reasons. If
+ the COM library has already been initialized on the current thread, false is returned and the
+ <computeroutput>.SystemErrorCode</computeroutput> is set to 1. There is also the possibility of a failure in initializing
+ the COM library. In this case, false is returned and the <computeroutput>.SystemErrorCode</computeroutput> is set to a
+ COM error code that describes the error.
+ </para>
</listitem></varlistentry>
<varlistentry><term><emphasis role="bold">Details</emphasis></term>
<listitem>
@@ -2343,23 +2363,42 @@
<varlistentry><term><emphasis role="bold">Return value:</emphasis></term>
<listitem>
<para>
- xx
+ Returns true if the current thread is the same thread as this <computeroutput>BrowseForFolder</computeroutput> object was
+ instantiated on, otherwise false. A return of false does not indicate failure.
</para>
</listitem></varlistentry>
<varlistentry><term><emphasis role="bold">Remarks:</emphasis></term>
<listitem>
<para>
- Additional comments.
+ As noted through out the <computeroutput>BrowseForFolder</computeroutput> documentation, the COM library must be
+ initialized and released for each thread the browse for folder object is used on. The ooDialog initializes the COM
+ library on the thread the object is first instantiated on and releases the COM library on the thread that the <xref
+ linkend="mthGetFolder"/> method, or the <xref linkend="mthGetItemIDList"/> is invoked on. If the same browse for folder
+ object is used on another thread than the thread it was instatiated on, the methods of the object may fail unless the COM
+ library is initialized on the other thread. The <xref linkend="mthInitCOM"/> method is provided to perform the
+ initialization, and the <emphasis role="italic">releaseCOM</emphasis> method is provided to release the COM library on
+ the other thread.
</para>
+ <para>
+ For each invocation of <emphasis role="italic">initCOM</emphasis> that returns true, a matching call to <emphasis
+ role="italic">releaseCOM</emphasis> must be made on the same thread. Note that the <xref linkend="mthGetFolder"/> and
+ <xref linkend="mthGetItemIDList"/> methods release the COM library on the thread they are executing in when the <emphasis
+ role="italic">reuse</emphasis> arguemnt is false. Therefore, if <emphasis role="italic">initCOM</emphasis> is invoked on
+ thread xx, the matching release COM requirement can be fulfilled by invoking <emphasis role="italic">getFolder</emphasis>
+ with the <emphasis role="italic">reuse</emphasis> argument set to false.
+ </para>
+ <para>
+ If <emphasis role="italic">initCOM</emphasis> returns false, then there is no need to invoke <emphasis
+ role="italic">releaseCOM</emphasis>. Indeed, invoking <emphasis role="italic">releaseCOM</emphasis> will be a mistake as
+ this will cause the matching <emphasis role="italic">initCOM</emphasis> / <emphasis role="italic">releaseCOM</emphasis>
+ calls to become unbalanced.
+ </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>
@@ -2468,7 +2507,7 @@
<varlistentry><term><emphasis role="bold">Arguments:</emphasis></term>
<listitem>
<para>
- The arguments are:
+ The single argument is;
</para>
<variablelist>
<varlistentry><term>itemIDList [required]</term>
@@ -2512,7 +2551,7 @@
<listitem>
<para>
This example configures a browse for folder dialog to allow browsing the entire shell namespace. It then runs in a loop
- allowing the user to pick a folder and see the folder's display name is. Note that every returned item ID list is
+ allowing the user to pick a folder and see what the folder's display name is. Note that every returned item ID list is
released. Also note that the <xref linkend="mthGetItemIDList"/> method uses true for the <emphasis
role="italic">reuse</emphasis> argument. This tells the ooDialog framework to not release COM during the invocation of
the <emphasis role="italic">getItemIDList</emphasis> method. Because of this the example uses <xref
@@ -2551,7 +2590,7 @@
return 0
- ::required 'ooDialog.cls'
+ ::requires 'ooDialog.cls'
]]>
</programlisting>
</para>
@@ -2559,7 +2598,6 @@
</variablelist>
</section> <!-- End BrowseForFolder::releaseItemIDList() -->
-
</section> <!-- End BrowseForFolder Class -->
|