From: <mie...@us...> - 2010-02-12 14:18:02
|
Revision: 5560 http://oorexx.svn.sourceforge.net/oorexx/?rev=5560&view=rev Author: miesfeld Date: 2010-02-12 14:17:53 +0000 (Fri, 12 Feb 2010) Log Message: ----------- ooDialog documentation work Modified Paths: -------------- docs/trunk/oodialog/basedialog.sgml docs/trunk/oodialog/dialogcontrolc.sgml Modified: docs/trunk/oodialog/basedialog.sgml =================================================================== --- docs/trunk/oodialog/basedialog.sgml 2010-02-12 04:29:27 UTC (rev 5559) +++ docs/trunk/oodialog/basedialog.sgml 2010-02-12 14:17:53 UTC (rev 5560) @@ -5258,25 +5258,21 @@ linkend="mthGetTextSizeScreen">getTextSizeScreen</link>() method. </para> <para> - In general, dialog units are only of value in laying out the dialog controls before the underlying - dialog is created. Once the underlying dialog is created, it makes more sense to work with pixels. - Historically, the ooDialog documentation did not make that distinction clear. In addition, dialog - units are tied directly to the font used by a dialog. Therefore, it does not make much sense for - this method to be an instance method of a dialog control. + In general, dialog units are only of value in laying out the dialog controls before the underlying dialog is + created. Once the underlying dialog is created, it makes more sense to work with pixels. Historically, the + ooDialog documentation did not make that distinction clear. In addition, dialog units are tied directly to the + font used by a specific dialog. Therefore, the window handle argument does not make much sens. </para> <para> - The normal use of this method would be to invoke it on a dialog object to help layout the dialog's - controls prior to the creation of the underlying dialog. In this use case, the hwnd argument is - meaningless. There is no handle to either the dialog window or any of its controls, prior to the - underlying dialog creation. There is little point in using a window handle from some other dialog. - However, to maintain compatibility with previous versions of ooDialog, the hwnd argument remains, and - the method is still an instance method of a dialog control. + The normal use of this method would be to invoke it on a dialog object to help layout the dialog's controls prior + to the creation of the underlying dialog. In this use case, the hwnd argument is meaningless. There is no window + handle for the dialog prior to the underlying dialog creation. There is little point in using a window handle + from some other dialog. The hwnd argument remains to maintain compatibility with previous versions of ooDialog. </para> <para> This method replaces the deprecated <link linkend="deprecatedDialogMethods">deprecated</link> <emphasis - role="italic">getTextSize</emphasis>() method. The compatibility restraint is a result of this. The - compatibility restraint makes it harder than necessary to document exactly how this method works, because the - behavior is different in places if the method is inovked on a dialog object or on a dialog control object. + role="italic">getTextSize</emphasis> method of the dialog object. Becuase of the backwards compatibility + restraint it is harder than necessary to document exactly how this method works. </para> <para> The ooDialog programmer is <emphasis role="bold">strongly</emphasis> encouraged to only inovke this Modified: docs/trunk/oodialog/dialogcontrolc.sgml =================================================================== --- docs/trunk/oodialog/dialogcontrolc.sgml 2010-02-12 04:29:27 UTC (rev 5559) +++ docs/trunk/oodialog/dialogcontrolc.sgml 2010-02-12 14:17:53 UTC (rev 5560) @@ -1877,6 +1877,139 @@ </para></note> </section> +<section id="mthGetTextSizeDlgClsDialogControl"><title>getTextSizeDlg</title> +<indexterm><primary>getTextSizeDlg</primary> +<secondary>DialogControl class</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--getTextSizeDlg(--text--+-------------+--+-------------+--+---------+--)---->< + +-,-fontname--+ +-,-fontSize--+ +-,-hwnd--+ +]]> +</programlisting> + +<para> + Calculates the size, (width and height,) needed to display the given text in the specified font. The + size is expressed in dialog units. To calculate the size in pixels use the <link + linkend="mthGetTextSizeScreen">getTextSizeScreen</link>() method. +</para> +<para> + In general, dialog units are only of value in laying out the dialog controls before the underlying dialog is + created. Once the underlying dialog is created, it makes more sense to work with pixels. Historically, the + ooDialog documentation did not make that distinction clear. In addition, dialog units are tied directly to the + font used by a specific dialog. Therefore, the window handle argument does not make much sense. In addition, it + does not make sense for this method to be a method of a dialog control. +</para> +<para> + The normal use of this method would be to invoke it on a dialog object to help layout the dialog's controls prior + to the creation of the underlying dialog. In this use case, the hwnd argument is meaningless. There is no window + handle for the dialog prior to the underlying dialog creation. There is little point in using a window handle + from some other dialog. The hwnd argument remains to maintain compatibility with previous versions of ooDialog. + Having this method a method of a dialog control is also to maintian backward compatibility. +</para> +<para> + This method replaces the deprecated <link linkend="deprecatedDialogControl">deprecated</link> <emphasis + role="italic">getTextSize</emphasis> method of the dialog object. Becausse of the backwards compatibility + restraint it is harder than necessary to document exactly how this method works. +</para> +<para> + The ooDialog programmer is <emphasis role="bold">strongly</emphasis> encouraged to only inovke this + method through a dialog object. Future versions of ooDialog may remove this method from the instance + methods of the <link linkend="clsDialogControl">DialogControl</link> class. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para>The arguments are: + <variablelist> + <varlistentry><term>text</term> + <listitem> + <para> + The string whose size is desired. If none of the optional arguments are specified then the font of the + dialog that owns the control is used to calculate the size. + </para> + <para> + However, there are some exceptions to this if the method is invoked <emphasis + role="italic">after</emphasis> the underlying dialog is created. + <orderedlist> + <listitem> + <para> + If this method is invoked through a dialog control object, then the size is calculated + using the dialog control font. This usage is deprecated and the ooDialog programmer is + <emphasis role="bold">strongly</emphasis> encouraged to not use this method in this manner. + </para> + </listitem> + <listitem> + <para> + If the fourth, optional, hwnd argument is used, then the font of that window is used to + calculate the size. Again, the ooDialog programmer is <emphasis + role="bold">strongly</emphasis> encouraged to not use this method in this manner. + </para> + </listitem> + </orderedlist> + </para> + </listitem></varlistentry> + <varlistentry><term>fontName</term> + <listitem> + <para> + Optional. The name of the font to use to calculate the size needed for the string. Use This + argument when the string will be displayed in a font <emphasis role="bold">different</emphasis> + than the dialog font. + </para> + </listitem></varlistentry> + <varlistentry><term>fontSize</term> + <listitem> + <para> + Optional. The size of the font named by the fontName argument. If this argument is omitted then + the defualt font size is used. (Currently the default size is 8.) + </para> + </listitem></varlistentry> + <varlistentry><term>hwnd</term> + <listitem> + <para> + Optional. A valid window handle. The font of this window is used to calculate the text size. + This argument is always ignored when the fontName argument is specified. As per the notes + above the ooDialog programmer is encouraged not to use this argument. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + The size needed for the string is returned in a <link linkend="clsSize">Size</link> object. The + size is specified in dialog units. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + This example calculates the size needed to display a message. It then uses that size to create an + object that holds the co-ordinates needed to place the text in a dialog. This is used in + defineDialog() to add the message text to the dialog. + <programlisting> + <![CDATA[ + size = self~getTextSizeDlg(message) + messageRect = .directory~new + messageRect~x = 10 + messageRect~y = 10 + messageRect~cx = size~width + messageRect~cy = size~height + ... + + ::method defineDialog + expose message messageRect okRect + + r = messageRect + self~addText(r~x, r~y, r~cx, r~cy, message) + + ]]> + </programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> <!-- End PlainBaseDialog::getTextSizeDlg() --> + </section> <section id="eventDialogControl"><title>Connect Event Methods</title> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |