From: <mie...@us...> - 2009-01-04 22:06:34
|
Revision: 3866 http://oorexx.svn.sourceforge.net/oorexx/?rev=3866&view=rev Author: miesfeld Date: 2009-01-04 21:47:15 +0000 (Sun, 04 Jan 2009) Log Message: ----------- Incremental update of ooDialog doc Modified Paths: -------------- docs/trunk/oodialog/Makefile docs/trunk/oodialog/oodialog.sgml docs/trunk/oodialog/preface.sgml Added Paths: ----------- docs/trunk/oodialog/overview.sgml Removed Paths: ------------- docs/trunk/oodialog/reference.sgml docs/trunk/oodialog/termdef.sgml Modified: docs/trunk/oodialog/Makefile =================================================================== --- docs/trunk/oodialog/Makefile 2009-01-04 20:45:53 UTC (rev 3865) +++ docs/trunk/oodialog/Makefile 2009-01-04 21:47:15 UTC (rev 3866) @@ -66,7 +66,7 @@ preface.sgml \ progressbarc.sgml \ propertysheetc.sgml \ - reference.sgml \ + overview.sgml \ resdialog.sgml \ scrollbarc.sgml \ slidercontrolc.sgml \ @@ -74,7 +74,6 @@ resources.sgml \ menus.sgml \ tabcontrolc.sgml \ - termdef.sgml \ treecontrolc.sgml \ userdialog.sgml \ ../shared/notices.sgml \ Modified: docs/trunk/oodialog/oodialog.sgml =================================================================== --- docs/trunk/oodialog/oodialog.sgml 2009-01-04 20:45:53 UTC (rev 3865) +++ docs/trunk/oodialog/oodialog.sgml 2009-01-04 21:47:15 UTC (rev 3866) @@ -3,7 +3,7 @@ [ <!ENTITY legalstuff SYSTEM "../shared/legalstuff.sgml"> <!ENTITY preface SYSTEM "preface.sgml"> -<!ENTITY reference SYSTEM "reference.sgml"> +<!ENTITY overview SYSTEM "overview.sgml"> <!ENTITY termdef SYSTEM "termdef.sgml"> <!ENTITY basedialog SYSTEM "basedialog.sgml"> <!ENTITY windowBaseCommon SYSTEM "windowBaseCommon.sgml"> @@ -94,15 +94,14 @@ &preface; <!-- About This Book --> <!-- start of body --> -&reference; <!-- Reference --> -&termdef; <!-- Definition of Terms --> +&overview; <!-- Brief overview --> &plainuserdialogc; <!-- PlainUserDialog Class --> +&standarddialog; <!-- Standard Dialogs, External Functions, and Public Routines --> &basedialog; <!-- BaseDialog Class --> &clsDialogControl; <!-- DialogControl Class --> &userdialog; <!-- UserDialog Class --> &resdialog; <!-- ResDialog Class --> &categorydialog; <!-- CategoryDialog Class --> -&standarddialog; <!-- Standard Dialogs, External Functions, and Public Routines --> &utilityclasses; <!-- Utility Classess, DlgUtil, Point, DlgArea, etc.. --> &clsMessageExtensions; <!-- MessageExtensions Class --> &clsAdvancedControls; <!-- AdvancedControl Class --> Copied: docs/trunk/oodialog/overview.sgml (from rev 3860, docs/trunk/oodialog/reference.sgml) =================================================================== --- docs/trunk/oodialog/overview.sgml (rev 0) +++ docs/trunk/oodialog/overview.sgml 2009-01-04 21:47:15 UTC (rev 3866) @@ -0,0 +1,537 @@ +<!--######################################################################### + # + # Description: Open Object Rexx: OODialog Reference SGML file. + # + # Copyright (c) 2005-2007, Rexx Language Association. All rights reserved. + # Portions Copyright (c) 2004, IBM Corporation. All rights reserved. + # + # This program and the accompanying materials are made available under + # the terms of the Common Public License v1.0 which accompanies this + # distribution. A copy is also available at the following address: + # http://www.oorexx.org/license.html + # + # Redistribution and use in source and binary forms, with or + # without modification, are permitted provided that the following + # conditions are met: + # + # Redistributions of source code must retain the above copyright + # notice, this list of conditions and the following disclaimer. + # Redistributions in binary form must reproduce the above copyright + # notice, this list of conditions and the following disclaimer in + # the documentation and/or other materials provided with the distribution. + # + # Neither the name of Rexx Language Association nor the names + # of its contributors may be used to endorse or promote products + # derived from this software without specific prior written permission. + # + # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS + # FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED + # TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, + # OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY + # OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + # + # Author(s): + # W. David Ashley <da...@us...> + # + ######################################################################### +--> +<chapter id="chapOverview"><title>Brief Overview</title> +<para> + This book is a reference to the ooDialog classes and the methods of those classes. There is little + documentation for the newcomer on how to get started using ooDialog. Until that type of documentation + can be written, the sample ooDialog programs that accompany the ooRexx distribution are probably the + best source of help in getting started. However, there are also numerous snippets of example code in + this book. +</para> + +<section id="reference"><title>OODialog Class Reference</title> +<para>The classes provided by OODialog form a hierarchy as shown in +<link linkend="fig52">The Hierarchy of OODialog Classes</link>.</para> + +<figure id="fig52"><title>The Hierarchy of OODialog Classes</title> +<mediaobject> +<imageobject> +<!-- Note! - if we include a /imagedata tag we get an error for DSSSL! --> +<imagedata fileref="rxou0s12.jpg" scale="40"> +</imageobject> +</mediaobject> +<mediaobject> +<imageobject> +<!-- Note! - if we include a /imagedata tag we get an error for DSSSL! --> +<imagedata fileref="rxou0s24.jpg" scale="40"> +</imageobject> +</mediaobject> +</figure> + +<para>The classes are: </para> +<variablelist> +<varlistentry><term>PlainBaseDialog, BaseDialog</term> +<listitem><para>Base methods regardless of whether the dialog is implemented as a binary +resource, a script, or dynamically. PlainBaseDialog provides limited functionality. +</para></listitem></varlistentry> +<varlistentry><term>PlainUserDialog</term> +<listitem><para>Subclass of PlainBaseDialog used to create a dialog with all its control +elements or to execute a dialog stored in a resource script (.RC). This class +has limited functionality. +</para></listitem></varlistentry> +<varlistentry><term>DynamicDialog, DialogExtensions, WindowBase, WindowExtensions</term> +<listitem><para>Internal mixin classes used to extend PlainBaseDialog, PlainUserDialog, +BaseDialog, UserDialog, and DialogControl. The methods provided by these classes +are not listed separately but are listed in BaseDialog or UserDialog. +</para></listitem></varlistentry> +<varlistentry><term>UserDialog</term> +<listitem><para>Subclass of BaseDialog used to create a dialog with all its control +elements, such as push buttons, check boxes, radio buttons, entry lines, and +list boxes. +</para></listitem></varlistentry> +<varlistentry><term>ResDialog</term> +<listitem><para>Subclass of BaseDialog for dialogs within a binary (compiled) resource +file (.DLL). +</para></listitem></varlistentry> +<varlistentry><term>CategoryDialog</term> +<listitem><para>Subclass of UserDialog used to create a dialog with several pages that +overlay each other. +</para></listitem></varlistentry> +<varlistentry><term>TimedMessage</term> +<listitem><para>Class to show a message window for a defined duration. +</para></listitem></varlistentry> +<varlistentry><term>InputBox</term> +<listitem><para>Class to dynamically define a dialog with a message, one entry line, +and two push buttons (OK, Cancel). +</para></listitem></varlistentry> +<varlistentry><term>PasswordBox</term> +<listitem><para>Similar to InputBox, but keystrokes in the entry line are shown as asterisks +(*). +</para></listitem></varlistentry> +<varlistentry><term>IntegerBox</term> +<listitem><para>Similar to InputBox, but only numeric data can be entered in the entry +line. +</para></listitem></varlistentry> +<varlistentry><term>MultiInputBox</term> +<listitem><para>Similar to InputBox, but with multiple entry lines. +</para></listitem></varlistentry> +<varlistentry><term>ListChoice</term> +<listitem><para>Class to dynamically define a dialog with a list box, where one line +can be selected and returned to the caller. +</para></listitem></varlistentry> +<varlistentry><term>MultiListChoice</term> +<listitem><para>Similar to ListChoice, but more than one line can be selected and returned +to the caller. +</para></listitem></varlistentry> +<varlistentry><term>CheckList</term> +<listitem><para>Class to dynamically define a dialog with a group of check boxes, which +can be selected and returned to the caller. +</para></listitem></varlistentry> +<varlistentry><term>SingleSelection</term> +<listitem><para>Class to dynamically define a dialog with a group of radio buttons, +where one can be selected and returned. +</para></listitem></varlistentry> +<varlistentry><term>Dialog</term> +<listitem><para>Subclass of UserDialog for simple dialogs. You can change the default +dialog style from UserDialog to ResDialog. +</para></listitem></varlistentry> +<varlistentry><term>AnimatedButton</term> +<listitem><para>Class to implement an animated button within a dialog. +</para></listitem></varlistentry> +<varlistentry><term>DialogControl</term> +<listitem><para>Class to implement methods that are common to all dialogs and dialog +controls. +</para></listitem></varlistentry> +<varlistentry><term>TreeControl</term> +<listitem><para>Class to implement a tree to display the list of items in a dialog in +a hierarchy. +</para></listitem></varlistentry> +<varlistentry><term>ListControl</term> +<listitem><para>Class to implement a list view to display the items in a dialog as a +collection. +</para></listitem></varlistentry> +<varlistentry><term>ProgressBar</term> +<listitem><para>Class to implement a progress indicator within a dialog. +</para></listitem></varlistentry> +<varlistentry><term>SliderControl</term> +<listitem><para>Class to implement a slider or trackbar within a dialog. +</para></listitem></varlistentry> +<varlistentry><term>TabControl</term> +<listitem><para>Class to implement tabs, which can be compared to dividers in a notebook +or labels in a file cabinet. +</para></listitem></varlistentry> +<varlistentry><term>StaticControl</term> +<listitem><para>Class to query and modify static controls, such as static text, group +boxes, and frames. +</para></listitem></varlistentry> +<varlistentry><term>EditControl</term> +<listitem><para>Class to query and modify edit controls, which are also called entry +lines. +</para></listitem></varlistentry> +<varlistentry><term>ButtonControl</term> +<listitem><para>Class to implement push buttons within a dialog. +</para></listitem></varlistentry> +<varlistentry><term>RadioButtonControl</term> +<listitem><para>Class to implement radio buttons within a dialog. +</para></listitem></varlistentry> +<varlistentry><term>CheckBoxControl</term> +<listitem><para>Class to implement check boxes within a dialog. +</para></listitem></varlistentry> +<varlistentry><term>ListBoxControl</term> +<listitem><para>Class to implement list boxes within a dialog. +</para></listitem></varlistentry> +<varlistentry><term>ComboBoxControl</term> +<listitem><para>Class to implement a combo box, which combines a list box with an edit +control. +</para></listitem></varlistentry> +<varlistentry><term>ScrollBarControl</term> +<listitem><para>Class to implement a scroll bar within a dialog. +</para></listitem></varlistentry> +<varlistentry><term>PropertySheetControl</term> +<listitem><para>Class to implement a property sheet, which is similar to a category +dialog that spreads its dialog items over several pages (categories), where +the individual pages are controlled by a tab control instead of radio buttons +or combo box lists. +</para></listitem></varlistentry> +</variablelist> +</section> + + +<section id="termdef"><title>Definition of Terms</title> +<variablelist> +<varlistentry><term id="resourceid">resource id</term> +<listitem><para>The identification number of a dialog resource. There are +several different types of dialog resources, menus, dialog controls, and bitmaps, +to name a few. You assign IDs when you create the resource definition for +your dialog. An ID can be either numerical (for example, 1) or symbolic (for +example, "IDOK"). +</para> +<para>IDs must be unique for each resource of the same type. Although two +resources of different types may have the same ID, when using symbolic IDs with +ooDialog, it is advisable to give all resources unique numerical IDs. +</para></listitem></varlistentry> +<varlistentry><term id="symbolicid">symbolic id</term> +<listitem><para>Defining a symbolic name for each numeric resource ID is often +useful in programs that work with resource IDs. The symbolic name is then used +where ever a numeric resource ID is needed. Symbolic names are easier to +remember than numeric IDs and can make the code easier to understand. +</para> +<para> + The mechanism ooDialog provides for using symbolic IDs is the <link linkend="constdir">ConstDir</link> + attribute of the dialog classes. This is a directory object where the indexes are symbolic IDs and the + item at each index is the numerical value of the ID. +</para> +<para> + Some generic <link linkend="chapResources">resources</link> are bound to the oodialog.dll. They can be + used in any ooDialog program and are accessed using the <link + linkend="clsResourceImage">.ResourceImage</link> class. Programmers should always use their symbolic + ID rather than their numeric ID in case the numeric value changes in future versions. To allow for + future expansion, the ooDialog programmer should consider the resource IDs of 1 through 50 as reserved + for ooDialog. Programmers can avoid conflicts by using IDs greater than 50 for resource IDs they assign + in their programs. +</para> +<para> + The symbolic IDs in the following table are pre-defined by ooDialog and placed in the + <computeroutput>ConstDir</computeroutput> when an instance of a dialog class is created. All symbolic + names after IDC_STATIC in the table refer to resources bound to oodialog.dll for general use by the + ooDialog programmer. +</para> +<table id="oodsymbolicids" frame="all"> +<title>Symbolic IDs Used by ooDialog</title> +<tgroup cols="3"> +<thead> +<row> +<entry>Numeric ID or Symbol</entry> +<entry>Symbolic ID</entry> +<entry>ResourceType</entry> +</row> +</thead> +<tbody> +<row> +<entry>1</entry> +<entry>IDOK</entry> +<entry>Button Control</entry> +</row> +<row> +<entry>2</entry> +<entry>IDCANCEL</entry> +<entry>Button Control</entry> +</row> +<row> +<entry>9</entry> +<entry>IDHELP</entry> +<entry>Button Control</entry> +</row> +<row> +<entry>-1</entry> +<entry>IDC_STATIC</entry> +<entry>Static Control</entry> +</row> +<row> +<entry>IDI_DLG_OODIALOG</entry> +<entry>IDI_DLG_OODIALOG</entry> +<entry>Icon</entry> +</row> +<row> +<entry>IDI_DLG_APPICON</entry> +<entry>IDI_DLG_APPICON</entry> +<entry>Icon</entry> +</row> +<row> +<entry>IDI_DLG_APPICON2</entry> +<entry>IDI_DLG_APPICON2</entry> +<entry>Icon</entry> +</row> +<row> +<entry>IDI_DLG_OOREXX</entry> +<entry>IDI_DLG_OOREXX</entry> +<entry>Icon</entry> +</row> +<row> +<entry>IDI_DLG_DEFAULT</entry> +<entry>IDI_DLG_DEFAULT</entry> +<entry>Icon</entry> +</row> +</tbody> +</tgroup> +</table> +</listitem></varlistentry> +<varlistentry><term id="pounddefine">#define statement</term> +<listitem><para>Define statements are often used in the C and C++ languages to +define symbolic names for numerical values. Because of this, it is common in +Windows programs with dialogs to define symbolic names for resource IDs. Most +Windows resource editors use symbolic IDs, (some to a limited degree, others +exclusively.) Often the define statements are put in a header file so they are +available both to the resource compiler and to the program code. The defines +take the form of: <computeroutput>#define symbolicName numericValue +</computeroutput> as in this example:</para> +<programlisting> +<![CDATA[ + +#define ID_PUSHBUTTON1 413 +#define ID_EDIT1 511 +#define ID_LISTBOX1 602 + +]]> +</programlisting> +<para>When ooDialog parses a resource script or a header file and finds a define +statement, it will add the symbolic ID to the <link linkend="constdir">ConstDir</link> +directory object of the dialog. Resource scripts are used by subclasses of the +<computeroutput>UserDialog</computeroutput> (see the <link linkend="h001613">Load</link> +method.) All the ooDialog dialog classes accept a header file as an optional +parameter when a new instance of a dialog object is created. (See for example +the <computeroutput>Init</computeroutput> method in the <link +linkend="h000025">BaseDialog</link> or <link linkend="h001531">UserDialog</link> +sections.) Symbolic IDs added to the <computeroutput>ConstDir</computeroutput> +can be used in any method of the ooDialog classes where a resource ID is needed. +</para></listitem></varlistentry> +<varlistentry><term id="headerfile">header file</term> +<listitem><para>A common practice when programming applications in Windows that +use dialogs and dialog resources is to place symbolic defines in a separate +file. These files often have a .h extension and are usually called header +files. Windows resource editors often manage a header file for the symbolic IDs +automatically. (For instance Microsoft's dialog editor creates, writes, and +reads the resource ID header file completely on its own. The user does not need +to take any action other than including the file in her program.) +</para></listitem></varlistentry> +<varlistentry><term>handle</term> +<listitem><para>A unique reference to a Windows object assigned by the system. +It can be a reference to a dialog, a particular dialog item, or a graphic +object (pen, brush, font). Handles are required for certain methods; they +can be retrieved from the system when needed. +</para></listitem></varlistentry> +<varlistentry><term id="dialogicon">dialog icon</term> +<listitem> +<para> + The term <emphasis role="italic">dialog icon</emphasis> is used in this documentation to refer to the + icon that is displayed in the left hand corner of the title bar of a dialog. In Windows this is often + called the <emphasis role="italic">application</emphasis> icon. The dialog icon is also used for the + Task Bar display and in the AltTab task switcher application. +</para> +<para> + The dialog icon for a specific dialog can be set when the dialog is run using one of the execute + methods. See the <link linkend="h000048">Execute</link> or <link linkend="popup">Popup</link> methods + for example. ooDialog provides four pre-defined icons for use in dialogs. Custom icons can be used by + including the icon in a binary (compiled) resource, a resource script, or by using the <link + linkend="mthAddIconClsUserDialog">addIcon</link> method of the UserDialog. The following table shows the symbolic IDs + of the pre-defined icons. The symbolic ID should always be used in case the numeric value is changed + in the future. Their numeric IDs should be considered reserved. There is a fifth symbolic ID that + represents the default dialog icon. This ID can always be used where a dialog icon ID is needed. +</para> +<table frame="all"> +<title>ooDialog Supplied Icons</title> +<tgroup cols="2"> +<thead> +<row> +<entry>Description</entry> +<entry>Symbolic ID</entry> +</row> +</thead> +<tbody> +<row> +<entry>The default, the letters OOD</entry> +<entry>IDI_DLG_OODIALOG</entry> +</row> +<row> +<entry>Dialog box image</entry> +<entry>IDI_DLG_APPICON</entry> +</row> +<row> +<entry>Fancier dialog box image</entry> +<entry>IDI_DLG_APPICON2</entry> +</row> +<row> +<entry>The ooRexx image</entry> +<entry>IDI_DLG_OOREXX</entry> +</row> +<row> +<entry>IDI_DLG_DEFAULT</entry> +<entry>IDI_DLG_DEFAULT</entry> +</row> +</tbody> +</tgroup> +</table> +</listitem></varlistentry> +<varlistentry><term>device context</term> +<listitem><para>Stores information about the graphic objects that are displayed, such +as bitmaps, lines, and pixels, and the tools used to display them, such as +pens, brushes, and fonts. A device context can be acquired for a dialog or +a button; it must be explicitly freed when the text or graphic operations +are completed. +</para></listitem></varlistentry> +<varlistentry><term id="comctl32">Common Controls Library (ComCtl32)</term> +<listitem> +<para> The dialog control windows used in dialogs, List-Views, Edit, + Tree-Views, etc., are supplied by Microsoft in the common controls library. + This is a DLL with the name comctl32.dll. Every version of Windows is + supplied with a common controls library. However, Microsoft has updated the + library a number of times to provide enhanced functionality and improved + features +</para> +<para> + Each new version of the library is backwards compatible with previous + versions, but will contain features not available in older versions. For + instance, some of the List-View <link linkend="listControlExtendedStyles"> + extended styles</link> are only available with a 6.0, or later, version of the + common controls library. ooDialog can only provide the features available in + the version of the common controls libray on the system ooDialog is running + on. +</para> +<para> + Therefore, an ooDialog program running on a Windows 2000 machine will not have + available some of the features that are available when ooDialog is running on + a XP service pack two system. The DlgUtil class provides a method, <link + linkend="mthComCtl32Version">comCtl32Version</link> that allows the programmer + to determine the exact version of the common controls library that ooDialog is + using. In the documentation for the ooDialog dialog control classes, features + that are not available in all versions of the common control library are + noted. The minimum version of the library that is needed is listed. In + general, at this time, all features of ooDialog are avaialable on Windows XP + or later. This may change in the future as Vista has common control features + not available on XP. +</para> +</listitem></varlistentry> +<varlistentry><term>pixel</term> +<listitem><para>Individual addressable point within a window. VGA screens support 640 +by 480 pixels, SVGA screens support higher resolutions, such as 800 by 600, +1024 by 768, 1280 by 1024, and 1600 by 1200. Pixel values in a dialog start +at the top left corner and include the window title and border. +</para></listitem></varlistentry> +<varlistentry><term>dialog unit</term> +<listitem><para>Used within dialog box templates to define the size and position of +the dialog box and its controls. There is a horizontal and a vertical dialog +base unit to convert width and height of dialog boxes and controls from dialog +units to pixels and vice versa. The value of these base units depend on the +screen resolution and the active system font; they are stored in attributes +of the UserDialog class. +<programlisting> +<![CDATA[ +xPixels = xDialogUnits * self~FactorX +]]> +</programlisting> +</para></listitem></varlistentry> +<varlistentry><term>color</term> +<listitem><para>Each color supported by the Windows operating system is assigned a +number. Sample color indexes are 0 (black), 1 (dark red), 2 (dark green), +3 (dark yellow), 4 (dark blue), 5 (purple), 6 (blue grey), 7 (light grey), +8 (pale green), 9 (light blue), 10 (white), 11 (grey), 12 (dark grey), 13 +(red), 14 (light green), 15 (yellow), 16 (blue), 17 (pink), 18 (turquoise). +</para></listitem></varlistentry> +<varlistentry><term>color palette</term> +<listitem><para>An array that contains color values identifying the colors that can +currently be displayed or drawn on the output device.</para> +<para>Color palettes are +used by devices that can generate many colors but can only display or draw +a subset of them at a time. For such devices, Windows maintains a system palette to +track and manage the current colors of the device.</para> +<para>Applications do not +have direct access to this system palette. Instead, Windows associates +a default palette with each device context. Applications can use the colors +in the default palette.</para> +<para>The default palette is an array of color values +identifying the colors that can be used with a device context by default. +Windows associates the default palette with a context whenever an application +creates a context for a device that supports color palettes. The default palette +ensures that colors are available for use by an application without any further +action. The default palette typically has 20 entries (colors), but the exact +number of entries can vary from device to device. The colors in the default +palette depend on the device. Display devices, for example, often use the +16 standard colors of the VGA display and 4 other colors defined by Windows. +</para></listitem></varlistentry> +<varlistentry><term id="windowsdoc">Windows documentation</term> +<listitem><para>The term <emphasis role="italic">Windows +documentation</emphasis> is used throughout the ooDialog reference to refer to +the Windows Operating System documentation provided by Microsoft. The +documentation is called the <emphasis role="bold">MSDN Library</emphasis>. The +library is provided online for anyone to access. In addition, since May 2006, +Microsoft has also provided free of charge the ISO images of the library +installation program. Anyone can download the ISOs, burn them to a CD and +install the library locally on their system. +</para> +<para>It is not necessary for the ooDialog programmer to know or understand the +underlying Windows API that ooDialog is built on. However, as programmers write +more sophisticated ooDialog applications, it may prove helpful to look up +certain details in the MSDN Library. The information below is provided to help +the ooDialog programmer locate the MSDN Library, if they would like to. All +things on the Internet change. The URLs listed here are accurate at the time of +this writing. +</para> +<para>The online MSDN Library is currently located at:</para> +<para>http://msdn2.microsoft.com/en-us/library/default.aspx.</para> +<para>Directions to the downloadable ISO images of the MSDN Library have been +posted on this blog entry:</para> +<para>http://blogs.msdn.com/robcaron/archive/2006/07/26/678897.aspx</para> +<para>A Google search using: <computeroutput>"Rob Caron" General Downloads MSDN +Library</computeroutput> should also turn up the blog entry. +</para></listitem></varlistentry> +<varlistentry><term id="platformsdk">Windows platform SDK</term> +<listitem><para>The <emphasis role="italic">Windows Platform SDK</emphasis> is +provided free of charge by Microsoft. The SDK is not needed to write ooDialog +programs. However, combining the use of the documentation in the MSDN Library +with the SDK allows very sophisticated ooDialog programs to be written. In +general, the ooDialog framework takes care of the low-level details needed to +work with the Windows API. However, there are a few generic ooDialog methods +that provide direct access to the Windows API. +</para> +<para>As an example, the <link linkend="h000141">AddUserMessage</link> method +allows the programmer to connect any Windows message sent to a dialog to a +method in his ooDialog class. To use this method, the programmer would go to +the MSDN library to look up details on the message and message parameters he is +interested in. He would then use the Platform SDK to determine the numeric +value of the Windows message and possibly the numeric values of its parameters. +</para> +<para>This link provides some good information on the Platform SDK in general +and also points the reader to where to get a SDK. +</para> +<para>http://en.wikipedia.org/wiki/Platform_SDK</para> +<para>Again, note that it is not at all necessary to obtain, or understand +details concerning, the Platform SDK. This information is provided for those +programmers that have reached the point where they think a method like +<computeroutput>AddUserMessage</computeroutput> might help them and need some +direction as to how to go about using it. +</para></listitem></varlistentry> +</variablelist> +</section> + +</chapter> Property changes on: docs/trunk/oodialog/overview.sgml ___________________________________________________________________ Added: svn:mergeinfo + Added: svn:eol-style + native Modified: docs/trunk/oodialog/preface.sgml =================================================================== --- docs/trunk/oodialog/preface.sgml 2009-01-04 20:45:53 UTC (rev 3865) +++ docs/trunk/oodialog/preface.sgml 2009-01-04 21:47:15 UTC (rev 3866) @@ -42,23 +42,40 @@ ######################################################################### --> <chapter id="preface"><title>About This Book</title> -<para>This book describes the OODialog class library in -Open Object Rexx on the <trademark class="registered">Windows</trademark> platform, -and how to use it to program user interfaces.</para> +<para> + This book describes the OODialog framework, which is implemented as an external library package, and + part of the Open Object Rexx distribution on the <trademark class="registered">Windows</trademark> + platform. It describes the classes in the framework and how to use the framework to program user + interfaces. +</para> <section id="whoshoulduse"><title>Who Should Use This Book</title> -<para>This book is intended for Object Rexx programmers who want to design graphical -user interfaces for their applications.</para> +<para> + This book is intended for Object Rexx programmers who want to design graphical user interfaces for + their applications. +</para> </section> <section id="bookstructure"><title>How This Book is Structured</title> -<para>This document used to be divided into two parts - a tutorial and a reference. -Unfortunately, the IBM Resource Workshop has not been contributed to the -open source community and is therefore not a part of the Open Object Rexx -project. So the tutorial section which covered the Resource Workshop has -been eliminated from this document.</para> -<para>However, the reference material which describes the classes and methods -in detail has been retained.</para> +<para> + This document should be divided into two parts - a tutorial and a reference. In the original + documentation accompanying IBM's Object Rexx, the documentation was in two parts. Unfortunately, the + tutorial portion mostly described how to use the IBM Resource Workshop. The Resource Workshop has not + been contributed to the open source community and is therefore not a part of the Open Object Rexx + project. Because the tutorial section was primarily directed towards using the Resource Workshop, it + does not make much sense in the current context. +</para> +<para> + This book is primarily a reference that describes the classes and methods in detail. There is no + tutorial. The tutorial portion needs to be written (or re-written depending on your point of view.) +</para> +<note><title><emphasis role="bold">Note</emphasis></title><para> + There is no loss of functionality in ooDialog because of the absence of the Resource Workshop. The + Windows resource format is well understood and there are any number of free or inexpensive resource + editors that do a better job of designing dialogs than the Resource Workshop did. (The Resource + Workshop was a 16-bit application with limited capacity for the newer features in the Windows user + interface.) ooDialog works fine with dialogs designed by any modern resource editor. +</para></note> </section> <section id="relinf"><title>Related Information</title> Deleted: docs/trunk/oodialog/reference.sgml =================================================================== --- docs/trunk/oodialog/reference.sgml 2009-01-04 20:45:53 UTC (rev 3865) +++ docs/trunk/oodialog/reference.sgml 2009-01-04 21:47:15 UTC (rev 3866) @@ -1,189 +0,0 @@ -<!--######################################################################### - # - # Description: Open Object Rexx: OODialog Reference SGML file. - # - # Copyright (c) 2005-2007, Rexx Language Association. All rights reserved. - # Portions Copyright (c) 2004, IBM Corporation. All rights reserved. - # - # This program and the accompanying materials are made available under - # the terms of the Common Public License v1.0 which accompanies this - # distribution. A copy is also available at the following address: - # http://www.oorexx.org/license.html - # - # Redistribution and use in source and binary forms, with or - # without modification, are permitted provided that the following - # conditions are met: - # - # Redistributions of source code must retain the above copyright - # notice, this list of conditions and the following disclaimer. - # Redistributions in binary form must reproduce the above copyright - # notice, this list of conditions and the following disclaimer in - # the documentation and/or other materials provided with the distribution. - # - # Neither the name of Rexx Language Association nor the names - # of its contributors may be used to endorse or promote products - # derived from this software without specific prior written permission. - # - # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS - # FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED - # TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, - # OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY - # OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING - # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS - # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - # - # Author(s): - # W. David Ashley <da...@us...> - # - ######################################################################### ---> -<chapter id="reference"><title>OODialog Method Reference</title> -<para>The classes provided by OODialog form a hierarchy as shown in -<link linkend="fig52">The Hierarchy of OODialog Classes</link>.</para> - -<figure id="fig52"><title>The Hierarchy of OODialog Classes</title> -<mediaobject> -<imageobject> -<!-- Note! - if we include a /imagedata tag we get an error for DSSSL! --> -<imagedata fileref="rxou0s12.jpg" scale="40"> -</imageobject> -</mediaobject> -<mediaobject> -<imageobject> -<!-- Note! - if we include a /imagedata tag we get an error for DSSSL! --> -<imagedata fileref="rxou0s24.jpg" scale="40"> -</imageobject> -</mediaobject> -</figure> - -<para>The classes are: </para> -<variablelist> -<varlistentry><term>PlainBaseDialog, BaseDialog</term> -<listitem><para>Base methods regardless of whether the dialog is implemented as a binary -resource, a script, or dynamically. PlainBaseDialog provides limited functionality. -</para></listitem></varlistentry> -<varlistentry><term>PlainUserDialog</term> -<listitem><para>Subclass of PlainBaseDialog used to create a dialog with all its control -elements or to execute a dialog stored in a resource script (.RC). This class -has limited functionality. -</para></listitem></varlistentry> -<varlistentry><term>DynamicDialog, DialogExtensions, WindowBase, WindowExtensions</term> -<listitem><para>Internal mixin classes used to extend PlainBaseDialog, PlainUserDialog, -BaseDialog, UserDialog, and DialogControl. The methods provided by these classes -are not listed separately but are listed in BaseDialog or UserDialog. -</para></listitem></varlistentry> -<varlistentry><term>UserDialog</term> -<listitem><para>Subclass of BaseDialog used to create a dialog with all its control -elements, such as push buttons, check boxes, radio buttons, entry lines, and -list boxes. -</para></listitem></varlistentry> -<varlistentry><term>ResDialog</term> -<listitem><para>Subclass of BaseDialog for dialogs within a binary (compiled) resource -file (.DLL). -</para></listitem></varlistentry> -<varlistentry><term>CategoryDialog</term> -<listitem><para>Subclass of UserDialog used to create a dialog with several pages that -overlay each other. -</para></listitem></varlistentry> -<varlistentry><term>TimedMessage</term> -<listitem><para>Class to show a message window for a defined duration. -</para></listitem></varlistentry> -<varlistentry><term>InputBox</term> -<listitem><para>Class to dynamically define a dialog with a message, one entry line, -and two push buttons (OK, Cancel). -</para></listitem></varlistentry> -<varlistentry><term>PasswordBox</term> -<listitem><para>Similar to InputBox, but keystrokes in the entry line are shown as asterisks -(*). -</para></listitem></varlistentry> -<varlistentry><term>IntegerBox</term> -<listitem><para>Similar to InputBox, but only numeric data can be entered in the entry -line. -</para></listitem></varlistentry> -<varlistentry><term>MultiInputBox</term> -<listitem><para>Similar to InputBox, but with multiple entry lines. -</para></listitem></varlistentry> -<varlistentry><term>ListChoice</term> -<listitem><para>Class to dynamically define a dialog with a list box, where one line -can be selected and returned to the caller. -</para></listitem></varlistentry> -<varlistentry><term>MultiListChoice</term> -<listitem><para>Similar to ListChoice, but more than one line can be selected and returned -to the caller. -</para></listitem></varlistentry> -<varlistentry><term>CheckList</term> -<listitem><para>Class to dynamically define a dialog with a group of check boxes, which -can be selected and returned to the caller. -</para></listitem></varlistentry> -<varlistentry><term>SingleSelection</term> -<listitem><para>Class to dynamically define a dialog with a group of radio buttons, -where one can be selected and returned. -</para></listitem></varlistentry> -<varlistentry><term>Dialog</term> -<listitem><para>Subclass of UserDialog for simple dialogs. You can change the default -dialog style from UserDialog to ResDialog. -</para></listitem></varlistentry> -<varlistentry><term>AnimatedButton</term> -<listitem><para>Class to implement an animated button within a dialog. -</para></listitem></varlistentry> -<varlistentry><term>DialogControl</term> -<listitem><para>Class to implement methods that are common to all dialogs and dialog -controls. -</para></listitem></varlistentry> -<varlistentry><term>TreeControl</term> -<listitem><para>Class to implement a tree to display the list of items in a dialog in -a hierarchy. -</para></listitem></varlistentry> -<varlistentry><term>ListControl</term> -<listitem><para>Class to implement a list view to display the items in a dialog as a -collection. -</para></listitem></varlistentry> -<varlistentry><term>ProgressBar</term> -<listitem><para>Class to implement a progress indicator within a dialog. -</para></listitem></varlistentry> -<varlistentry><term>SliderControl</term> -<listitem><para>Class to implement a slider or trackbar within a dialog. -</para></listitem></varlistentry> -<varlistentry><term>TabControl</term> -<listitem><para>Class to implement tabs, which can be compared to dividers in a notebook -or labels in a file cabinet. -</para></listitem></varlistentry> -<varlistentry><term>StaticControl</term> -<listitem><para>Class to query and modify static controls, such as static text, group -boxes, and frames. -</para></listitem></varlistentry> -<varlistentry><term>EditControl</term> -<listitem><para>Class to query and modify edit controls, which are also called entry -lines. -</para></listitem></varlistentry> -<varlistentry><term>ButtonControl</term> -<listitem><para>Class to implement push buttons within a dialog. -</para></listitem></varlistentry> -<varlistentry><term>RadioButtonControl</term> -<listitem><para>Class to implement radio buttons within a dialog. -</para></listitem></varlistentry> -<varlistentry><term>CheckBoxControl</term> -<listitem><para>Class to implement check boxes within a dialog. -</para></listitem></varlistentry> -<varlistentry><term>ListBoxControl</term> -<listitem><para>Class to implement list boxes within a dialog. -</para></listitem></varlistentry> -<varlistentry><term>ComboBoxControl</term> -<listitem><para>Class to implement a combo box, which combines a list box with an edit -control. -</para></listitem></varlistentry> -<varlistentry><term>ScrollBarControl</term> -<listitem><para>Class to implement a scroll bar within a dialog. -</para></listitem></varlistentry> -<varlistentry><term>PropertySheetControl</term> -<listitem><para>Class to implement a property sheet, which is similar to a category -dialog that spreads its dialog items over several pages (categories), where -the individual pages are controlled by a tab control instead of radio buttons -or combo box lists. -</para></listitem></varlistentry> -</variablelist> -</chapter> Deleted: docs/trunk/oodialog/termdef.sgml =================================================================== --- docs/trunk/oodialog/termdef.sgml 2009-01-04 20:45:53 UTC (rev 3865) +++ docs/trunk/oodialog/termdef.sgml 2009-01-04 21:47:15 UTC (rev 3866) @@ -1,378 +0,0 @@ -<!--######################################################################### - # - # Description: Open Object Rexx: OODialog Reference SGML file. - # - # Copyright (c) 2005-2007, Rexx Language Association. All rights reserved. - # Portions Copyright (c) 2004, IBM Corporation. All rights reserved. - # - # This program and the accompanying materials are made available under - # the terms of the Common Public License v1.0 which accompanies this - # distribution. A copy is also available at the following address: - # http://www.oorexx.org/license.html - # - # Redistribution and use in source and binary forms, with or - # without modification, are permitted provided that the following - # conditions are met: - # - # Redistributions of source code must retain the above copyright - # notice, this list of conditions and the following disclaimer. - # Redistributions in binary form must reproduce the above copyright - # notice, this list of conditions and the following disclaimer in - # the documentation and/or other materials provided with the distribution. - # - # Neither the name of Rexx Language Association nor the names - # of its contributors may be used to endorse or promote products - # derived from this software without specific prior written permission. - # - # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS - # FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED - # TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, - # OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY - # OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING - # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS - # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - # - # Author(s): - # W. David Ashley <da...@us...> - # - ######################################################################### ---> -<chapter id="termdef"><title>Definition of Terms</title> -<variablelist> -<varlistentry><term id="resourceid">resource id</term> -<listitem><para>The identification number of a dialog resource. There are -several different types of dialog resources, menus, dialog controls, and bitmaps, -to name a few. You assign IDs when you create the resource definition for -your dialog. An ID can be either numerical (for example, 1) or symbolic (for -example, "IDOK"). -</para> -<para>IDs must be unique for each resource of the same type. Although two -resources of different types may have the same ID, when using symbolic IDs with -ooDialog, it is advisable to give all resources unique numerical IDs. -</para></listitem></varlistentry> -<varlistentry><term id="symbolicid">symbolic id</term> -<listitem><para>Defining a symbolic name for each numeric resource ID is often -useful in programs that work with resource IDs. The symbolic name is then used -where ever a numeric resource ID is needed. Symbolic names are easier to -remember than numeric IDs and can make the code easier to understand. -</para> -<para> - The mechanism ooDialog provides for using symbolic IDs is the <link linkend="constdir">ConstDir</link> - attribute of the dialog classes. This is a directory object where the indexes are symbolic IDs and the - item at each index is the numerical value of the ID. -</para> -<para> - Some generic <link linkend="chapResources">resources</link> are bound to the oodialog.dll. They can be - used in any ooDialog program and are accessed using the <link - linkend="clsResourceImage">.ResourceImage</link> class. Programmers should always use their symbolic - ID rather than their numeric ID in case the numeric value changes in future versions. To allow for - future expansion, the ooDialog programmer should consider the resource IDs of 1 through 50 as reserved - for ooDialog. Programmers can avoid conflicts by using IDs greater than 50 for resource IDs they assign - in their programs. -</para> -<para> - The symbolic IDs in the following table are pre-defined by ooDialog and placed in the - <computeroutput>ConstDir</computeroutput> when an instance of a dialog class is created. All symbolic - names after IDC_STATIC in the table refer to resources bound to oodialog.dll for general use by the - ooDialog programmer. -</para> -<table id="oodsymbolicids" frame="all"> -<title>Symbolic IDs Used by ooDialog</title> -<tgroup cols="3"> -<thead> -<row> -<entry>Numeric ID or Symbol</entry> -<entry>Symbolic ID</entry> -<entry>ResourceType</entry> -</row> -</thead> -<tbody> -<row> -<entry>1</entry> -<entry>IDOK</entry> -<entry>Button Control</entry> -</row> -<row> -<entry>2</entry> -<entry>IDCANCEL</entry> -<entry>Button Control</entry> -</row> -<row> -<entry>9</entry> -<entry>IDHELP</entry> -<entry>Button Control</entry> -</row> -<row> -<entry>-1</entry> -<entry>IDC_STATIC</entry> -<entry>Static Control</entry> -</row> -<row> -<entry>IDI_DLG_OODIALOG</entry> -<entry>IDI_DLG_OODIALOG</entry> -<entry>Icon</entry> -</row> -<row> -<entry>IDI_DLG_APPICON</entry> -<entry>IDI_DLG_APPICON</entry> -<entry>Icon</entry> -</row> -<row> -<entry>IDI_DLG_APPICON2</entry> -<entry>IDI_DLG_APPICON2</entry> -<entry>Icon</entry> -</row> -<row> -<entry>IDI_DLG_OOREXX</entry> -<entry>IDI_DLG_OOREXX</entry> -<entry>Icon</entry> -</row> -<row> -<entry>IDI_DLG_DEFAULT</entry> -<entry>IDI_DLG_DEFAULT</entry> -<entry>Icon</entry> -</row> -</tbody> -</tgroup> -</table> -</listitem></varlistentry> -<varlistentry><term id="pounddefine">#define statement</term> -<listitem><para>Define statements are often used in the C and C++ languages to -define symbolic names for numerical values. Because of this, it is common in -Windows programs with dialogs to define symbolic names for resource IDs. Most -Windows resource editors use symbolic IDs, (some to a limited degree, others -exclusively.) Often the define statements are put in a header file so they are -available both to the resource compiler and to the program code. The defines -take the form of: <computeroutput>#define symbolicName numericValue -</computeroutput> as in this example:</para> -<programlisting> -<![CDATA[ - -#define ID_PUSHBUTTON1 413 -#define ID_EDIT1 511 -#define ID_LISTBOX1 602 - -]]> -</programlisting> -<para>When ooDialog parses a resource script or a header file and finds a define -statement, it will add the symbolic ID to the <link linkend="constdir">ConstDir</link> -directory object of the dialog. Resource scripts are used by subclasses of the -<computeroutput>UserDialog</computeroutput> (see the <link linkend="h001613">Load</link> -method.) All the ooDialog dialog classes accept a header file as an optional -parameter when a new instance of a dialog object is created. (See for example -the <computeroutput>Init</computeroutput> method in the <link -linkend="h000025">BaseDialog</link> or <link linkend="h001531">UserDialog</link> -sections.) Symbolic IDs added to the <computeroutput>ConstDir</computeroutput> -can be used in any method of the ooDialog classes where a resource ID is needed. -</para></listitem></varlistentry> -<varlistentry><term id="headerfile">header file</term> -<listitem><para>A common practice when programming applications in Windows that -use dialogs and dialog resources is to place symbolic defines in a separate -file. These files often have a .h extension and are usually called header -files. Windows resource editors often manage a header file for the symbolic IDs -automatically. (For instance Microsoft's dialog editor creates, writes, and -reads the resource ID header file completely on its own. The user does not need -to take any action other than including the file in her program.) -</para></listitem></varlistentry> -<varlistentry><term>handle</term> -<listitem><para>A unique reference to a Windows object assigned by the system. -It can be a reference to a dialog, a particular dialog item, or a graphic -object (pen, brush, font). Handles are required for certain methods; they -can be retrieved from the system when needed. -</para></listitem></varlistentry> -<varlistentry><term id="dialogicon">dialog icon</term> -<listitem> -<para> - The term <emphasis role="italic">dialog icon</emphasis> is used in this documentation to refer to the - icon that is displayed in the left hand corner of the title bar of a dialog. In Windows this is often - called the <emphasis role="italic">application</emphasis> icon. The dialog icon is also used for the - Task Bar display and in the AltTab task switcher application. -</para> -<para> - The dialog icon for a specific dialog can be set when the dialog is run using one of the execute - methods. See the <link linkend="h000048">Execute</link> or <link linkend="popup">Popup</link> methods - for example. ooDialog provides four pre-defined icons for use in dialogs. Custom icons can be used by - including the icon in a binary (compiled) resource, a resource script, or by using the <link - linkend="mthAddIconClsUserDialog">addIcon</link> method of the UserDialog. The following table shows the symbolic IDs - of the pre-defined icons. The symbolic ID should always be used in case the numeric value is changed - in the future. Their numeric IDs should be considered reserved. There is a fifth symbolic ID that - represents the default dialog icon. This ID can always be used where a dialog icon ID is needed. -</para> -<table frame="all"> -<title>ooDialog Supplied Icons</title> -<tgroup cols="2"> -<thead> -<row> -<entry>Description</entry> -<entry>Symbolic ID</entry> -</row> -</thead> -<tbody> -<row> -<entry>The default, the letters OOD</entry> -<entry>IDI_DLG_OODIALOG</entry> -</row> -<row> -<entry>Dialog box image</entry> -<entry>IDI_DLG_APPICON</entry> -</row> -<row> -<entry>Fancier dialog box image</entry> -<entry>IDI_DLG_APPICON2</entry> -</row> -<row> -<entry>The ooRexx image</entry> -<entry>IDI_DLG_OOREXX</entry> -</row> -<row> -<entry>IDI_DLG_DEFAULT</entry> -<entry>IDI_DLG_DEFAULT</entry> -</row> -</tbody> -</tgroup> -</table> -</listitem></varlistentry> -<varlistentry><term>device context</term> -<listitem><para>Stores information about the graphic objects that are displayed, such -as bitmaps, lines, and pixels, and the tools used to display them, such as -pens, brushes, and fonts. A device context can be acquired for a dialog or -a button; it must be explicitly freed when the text or graphic operations -are completed. -</para></listitem></varlistentry> -<varlistentry><term id="comctl32">Common Controls Library (ComCtl32)</term> -<listitem> -<para> The dialog control windows used in dialogs, List-Views, Edit, - Tree-Views, etc., are supplied by Microsoft in the common controls library. - This is a DLL with the name comctl32.dll. Every version of Windows is - supplied with a common controls library. However, Microsoft has updated the - library a number of times to provide enhanced functionality and improved - features -</para> -<para> - Each new version of the library is backwards compatible with previous - versions, but will contain features not available in older versions. For - instance, some of the List-View <link linkend="listControlExtendedStyles"> - extended styles</link> are only available with a 6.0, or later, version of the - common controls library. ooDialog can only provide the features available in - the version of the common controls libray on the system ooDialog is running - on. -</para> -<para> - Therefore, an ooDialog program running on a Windows 2000 machine will not have - available some of the features that are available when ooDialog is running on - a XP service pack two system. The DlgUtil class provides a method, <link - linkend="mthComCtl32Version">comCtl32Version</link> that allows the programmer - to determine the exact version of the common controls library that ooDialog is - using. In the documentation for the ooDialog dialog control classes, features - that are not available in all versions of the common control library are - noted. The minimum version of the library that is needed is listed. In - general, at this time, all features of ooDialog are avaialable on Windows XP - or later. This may change in the future as Vista has common control features - not available on XP. -</para> -</listitem></varlistentry> -<varlistentry><term>pixel</term> -<listitem><para>Individual addressable point within a window. VGA screens support 640 -by 480 pixels, SVGA screens support higher resolutions, such as 800 by 600, -1024 by 768, 1280 by 1024, and 1600 by 1200. Pixel values in a dialog start -at the top left corner and include the window title and border. -</para></listitem></varlistentry> -<varlistentry><term>dialog unit</term> -<listitem><para>Used within dialog box templates to define the size and position of -the dialog box and its controls. There is a horizontal and a vertical dialog -base unit to convert width and height of dialog boxes and controls from dialog -units to pixels and vice versa. The value of these base units depend on the -screen resolution and the active system font; they are stored in attributes -of the UserDialog class. -<programlisting> -<![CDATA[ -xPixels = xDialogUnits * self~FactorX -]]> -</programlisting> -</para></listitem></varlistentry> -<varlistentry><term>color</term> -<listitem><para>Each color supported by the Windows operating system is assigned a -number. Sample color indexes are 0 (black), 1 (dark red), 2 (dark green), -3 (dark yellow), 4 (dark blue), 5 (purple), 6 (blue grey), 7 (light grey), -8 (pale green), 9 (light blue), 10 (white), 11 (grey), 12 (dark grey), 13 -(red), 14 (light green), 15 (yellow), 16 (blue), 17 (pink), 18 (turquoise). -</para></listitem></varlistentry> -<varlistentry><term>color palette</term> -<listitem><para>An array that contains color values identifying the colors that can -currently be displayed or drawn on the output device.</para> -<para>Color palettes are -used by devices that can generate many colors but can only display or draw -a subset of them at a time. For such devices, Windows maintains a system palette to -track and manage the current colors of the device.</para> -<para>Applications do not -have direct access to this system palette. Instead, Windows associates -a default palette with each device context. Applications can use the colors -in the default palette.</para> -<para>The default palette is an array of color values -identifying the colors that can be used with a device context by default. -Windows associates the default palette with a context whenever an application -creates a context for a device that supports color palettes. The default palette -ensures that colors are available for use by an application without any further -action. The default palette typically has 20 entries (colors), but the exact -number of entries can vary from device to device. The colors in the default -palette depend on the device. Display devices, for example, often use the -16 standard colors of the VGA display and 4 other colors defined by Windows. -</para></listitem></varlistentry> -<varlistentry><term id="windowsdoc">Windows documentation</term> -<listitem><para>The term <emphasis role="italic">Windows -documentation</emphasis> is used throughout the ooDialog reference to refer to -the Windows Operating System documentation provided by Microsoft. The -documentation is called the <emphasis role="bold">MSDN Library</emphasis>. The -library is provided online for anyone to access. In addition, since May 2006, -Microsoft has also provided free of charge the ISO images of the library -installation program. Anyone can download the ISOs, burn them to a CD and -install the library locally on their system. -</para> -<para>It is not necessary for the ooDialog programmer to know or understand the -underlying Windows API that ooDialog is built on. However, as programmers write -more sophisticated ooDialog applications, it may prove helpful to look up -certain details in the MSDN Library. The information below is provided to help -the ooDialog programmer locate the MSDN Library, if they would like to. All -things on the Internet change. The URLs listed here are accurate at the time of -this writing. -</para> -<para>The online MSDN Library is currently located at:</para> -<para>http://msdn2.microsoft.com/en-us/library/default.aspx.</para> -<para>Directions to the downloadable ISO images of the MSDN Library have been -posted on this blog entry:</para> -<para>http://blogs.msdn.com/robcaron/archive/2006/07/26/678897.aspx</para> -<para>A Google search using: <computeroutput>"Rob Caron" General Downloads MSDN -Library</computeroutput> should also turn up the blog entry. -</para></listitem></varlistentry> -<varlistentry><term id="platformsdk">Windows platform SDK</term> -<listitem><para>The <emphasis role="italic">Windows Platform SDK</emphasis> is -provided free of charge by Microsoft. The SDK is not needed to write ooDialog -programs. However, combining the use of the documentation in the MSDN Library -with the SDK allows very sophisticated ooDialog programs to be written. In -general, the ooDialog framework takes care of the low-level details needed to -work with the Windows API. However, there are a few generic ooDialog methods -that provide direct access to the Windows API. -</para> -<para>As an example, the <link linkend="h000141">AddUserMessage</link> method -allows the programmer to connect any Windows message sent to a dialog to a -method in his ooDialog class. To use this method, the programmer would go to -the MSDN library to look up details on the message and message parameters... [truncated message content] |