Menu
▾
▴
[Oorexx-svn] SF.net SVN: oorexx-code-0:[9549] docs/trunk/oodialog/en-US/utilityclasses. xml
|
From: <mie...@us...> - 2013-11-23 18:52:54
|
Revision: 9549
http://sourceforge.net/p/oorexx/code-0/9549
Author: miesfeld
Date: 2013-11-23 18:52:52 +0000 (Sat, 23 Nov 2013)
Log Message:
-----------
#559 ooDialog - add a convenience function to help locate resource files
Modified Paths:
--------------
docs/trunk/oodialog/en-US/utilityclasses.xml
Modified: docs/trunk/oodialog/en-US/utilityclasses.xml
===================================================================
--- docs/trunk/oodialog/en-US/utilityclasses.xml 2013-11-23 18:42:09 UTC (rev 9548)
+++ docs/trunk/oodialog/en-US/utilityclasses.xml 2013-11-23 18:52:52 UTC (rev 9549)
@@ -102,6 +102,10 @@
<entry>Searches the desktop for a specific window and returns its handle.</entry>
</row>
<row>
+<entry><xref linkend="rtnLocate"/></entry>
+<entry>Returns the directory containing the Rexx source code file that <emphasis role="italic">locate</emphasis> is executing in. Similar to <emphasis role="italic">parse source</emphasis>.</entry>
+</row>
+<row>
<entry><xref linkend="rtnMSSleep"/></entry>
<entry>Sleeps for the specified number of milliseconds.</entry>
</row>
@@ -247,6 +251,10 @@
<entry>A directory object that maps symbolic resource IDS to their numeric IDs</entry>
</row>
<row>
+<entry><xref linkend="atrSrcDir"/></entry>
+<entry>Reflects the complete path name of the directory the main program file is located in, provided the <xref linkend="rtnLocate"/> method has been executed in the interpreter process.</entry>
+</row>
+<row>
<entry align="center"><emphasis role="bold">Instance Methods</emphasis></entry>
<entry align="center"><emphasis role="bold"></emphasis></entry>
</row>
@@ -323,6 +331,99 @@
</programlisting>
</section>
+<section id="atrSrcDir" xreflabel="srcDir"><title>srcDir (Attribute)</title>
+<indexterm><primary>srcDir</primary></indexterm>
+<indexterm><primary>ApplicationManager class</primary><secondary>srcDir</secondary></indexterm>
+<programlisting>
+<![CDATA[
+>>--srcDir-----------------------------------------------------><
+
+>>--srcDir = varName-------------------------------------------><
+
+]]>
+</programlisting>
+
+<para>
+ Reflects the complete path name of the directory the main program file is located in, provided the <xref
+ linkend="rtnLocate"/> method has been executed in the interpreter process. The path name includes the trailing slash
+ (<emphasis role="italic">\</emphasis>.)
+</para>
+<variablelist>
+ <varlistentry><term><emphasis role="bold">srcDir get:</emphasis></term>
+ <listitem>
+ <para>
+ Returns a complete path name of a directory, or the <computeroutput>.nil</computeroutput> object if the <xref
+ linkend="rtnLocate"/> is not been executed.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><emphasis role="bold">srcDir set:</emphasis></term>
+ <listitem>
+ <para>
+ The programmer can not set the value of this attribute directly. The ooDialog framework sets, or resets, its value when
+ the <emphasis role="italic">locate</emphasis> routine is executed.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term>
+ <listitem>
+ <para>
+ The purpose of the <emphasis role="italic">locate</emphasis> function and the <emphasis role="italic">srcDir</emphasis>
+ attribute is to help the programmer create complete path names for any auxiliary files needed by an application. This
+ allows the application to execute correctly, even if started from a directory other than its installtion directory. The
+ documentation for the <xref linkend="rtnLocate"/> routine contains some additional insight into this purpose.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><emphasis role="bold">Details</emphasis></term>
+ <listitem>
+ <para>
+ Raises syntax errors when incorrect usage is detected.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><emphasis role="bold">Example:</emphasis></term>
+ <listitem>
+ <para>
+ This example shows the <emphasis role="italic">locate</emphasis> function being used to get the installation directory of
+ an application and then the <emphasis role="italic">srcDir</emphasis> attribute being used to access the directory value
+ in a private method of a class:
+<programlisting>
+<![CDATA[
+ srcDir = locate()
+
+ rcFile = srcDir"resources\imageButton.rc"
+ symbolFile = srcDir"resources\imageButton.h"
+
+ .application~setDefaults("O", symbolFile, .false)
+
+ dlg = .ImageListDlg~new(rcFile, IDD_IMAGELIST_BUTTON)
+ ...
+
+::class 'ImageListDlg' subclass RcDialog
+ ...
+
+::method setPictureButtons private
+ expose pbView pbAdd stStatus imagesLoaded imageList
+
+ if .DlgUtil~comCtl32Version < 6 then return self~oldSetButtons
+
+ pbView~style = "MULTILINE BOTTOM"
+
+ srcDir = .application~srcDir
+
+ -- The images are loaded from files.
+ files = .array~new()
+ files[1] = srcDir"resources\Normal.bmp" -- Normal
+ files[2] = srcDir"resources\Hot.bmp" -- Hot (hover)
+ files[3] = srcDir"resources\Pushed.bmp" -- Pushed
+ files[4] = srcDir"resources\Disabled.bmp" -- Disabled
+ files[5] = srcDir"resources\Default.bmp" -- Default button
+ files[6] = srcDir"resources\Hot.bmp" -- Stylus hot, tablet PC only
+ ...
+]]>
+</programlisting>
+ </para>
+ </listitem></varlistentry>
+</variablelist>
+</section> <!-- End ApplicationManager::srcDir() [attribute] -->
+
<section id="mthAddToConstDir" xreflabel="addToConstDir"><title>addToConstDir</title>
<indexterm><primary>addToConstDir</primary></indexterm>
<indexterm><primary>ApplicationManager class</primary><secondary>addToConstDir</secondary></indexterm>
@@ -3056,6 +3157,117 @@
</section>
+<section id="rtnLocate"><title>locate</title>
+<indexterm><primary>locate</primary></indexterm>
+<indexterm><primary>public routines</primary><secondary>locate</secondary></indexterm>
+<programlisting>
+<![CDATA[
+>>--locate(--+----------+--)---------------------><
+ +--update--+
+]]>
+</programlisting>
+
+<para>
+ Returns the directory containing the Rexx source code file that <emphasis role="italic">locate</emphasis> is executing in.
+ This is similar to <emphasis role="italic">parse source</emphasis>, but returns the complete directory path rather than the
+ complete file name. In addition, <emphasis role="italic">locate</emphasis> sets the value of the <xref
+ linkend="atrSrcDir"/> attribute of the <xref linkend="dotApplication"/> to the complete directory path name.
+</para>
+<variablelist>
+ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term>
+ <listitem>
+ <para>
+ The single argument is:
+ <variablelist>
+ <varlistentry><term>update [optional]</term>
+ <listitem>
+ <para>
+ By default this routine only sets the <computeroutput>.aplication's</computeroutput> <emphasis
+ role="italic">srcDir</emphasis> attriute the first time it is invoked. On succesive invocations, it does not change
+ the attribute. If update is true, it resets the <computeroutput>.aplication's</computeroutput> <emphasis
+ role="italic">srcDir</emphasis> attriute to the value it is returning.
+ </para>
+ </listitem></varlistentry>
+ </variablelist>
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><emphasis role="bold">Return value:</emphasis></term>
+ <listitem>
+ <para>
+ Returns the complete path name, including the trailing slash (<emphasis role="italic">\</emphasis>,) of the directory the
+ source code file containing the executing <emphasis role="italic">locate</emphasis> is located in.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term>
+ <listitem>
+ <para>
+ The primary purpose of the <emphasis role="italic">locate</emphasis> function is to help the ooDialog programmer create
+ complete path names for any resource files, or other auxiliary files, needed by an application. This in turns allows the
+ application to be executed from any directory. The <emphasis role="italic">locate</emphasis> function is a conveience
+ function. The same functionality can be achieved using <emphasis role="italic">parse source</emphasis> and some mechanism
+ for retaining the directory value.
+ </para>
+ <para>
+ Typically, <emphasis role="italic">locate</emphasis> function would be executed once during the start up of an
+ application and the <emphasis role="italic">srcDir</emphasis> attribute of the <emphasis
+ role="italic">.application</emphasis> object would be used elsewhere in the application to gain access to the directory
+ value. If the programmer chooses to execute <emphasis role="italic">locate</emphasis> more than once, then she would need
+ to decide if the <emphasis role="italic">srcDir</emphasis> attribute's value shoud be updated with the new direcotry
+ value. Assuming, <emphasis role="italic">locate</emphasis> is returning a new value. This is the purpose of the <emphasis
+ role="italic">update</emphasis> argument. By default, the <emphasis role="italic">srcDir</emphasis> attribute will not be
+ changed. Pass true as the first argument to <emphasis role="italic">locate</emphasis> to force the routine to update the
+ <emphasis role="italic">srcDir</emphasis> attribute.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><emphasis role="bold">Example:</emphasis></term>
+ <listitem>
+ <para>
+ This example comes from an application that has its resource files located in a subdirectory of the main application
+ directory. The <emphasis role="italic">locate</emphasis> function is used to get the complete path name of the directory
+ the main program file is in and then the returned value is used to construct complete path names to the application's
+ resource files:
+<programlisting>
+<![CDATA[
+
+ srcDir = locate()
+
+ rcFile = srcDir"resources\imageButton.rc"
+ symbolFile = srcDir"resources\imageButton.h"
+
+ .application~setDefaults("O", symbolFile, .false)
+
+ dlg = .ImageListDlg~new(rcFile, IDD_IMAGELIST_BUTTON)
+ ...
+
+::class 'ImageListDlg' subclass RcDialog
+ ...
+
+::method setPictureButtons private
+ expose pbView pbAdd stStatus imagesLoaded imageList
+
+ if .DlgUtil~comCtl32Version < 6 then return self~oldSetButtons
+
+ pbView~style = "MULTILINE BOTTOM"
+
+ srcDir = .application~srcDir
+
+ -- The images are loaded from files.
+ files = .array~new()
+ files[1] = srcDir"resources\Normal.bmp" -- Normal
+ files[2] = srcDir"resources\Hot.bmp" -- Hot (hover)
+ files[3] = srcDir"resources\Pushed.bmp" -- Pushed
+ files[4] = srcDir"resources\Disabled.bmp" -- Disabled
+ files[5] = srcDir"resources\Default.bmp" -- Default button
+ files[6] = srcDir"resources\Hot.bmp" -- Stylus hot, tablet PC only
+ ...
+]]>
+</programlisting>
+ </para>
+ </listitem></varlistentry>
+</variablelist>
+</section> <!-- End locate() -->
+
+
<section id="rtnMSSleep" xreflabel="MSSleep"><title>MSSleep Routine</title>
<indexterm><primary>MSSleep</primary></indexterm>
<indexterm><primary>public routines</primary>
|