DlgUtil Class

All the methods of the DlgUitl class are class methods. There are no instance methods, other than inherited methods, for this class. The class methods are a collection of common utilities, mostly for converting different Windows values, getting version information, and the like.

Requires:

The DlgUtil class requires the class definition file oodPlain.cls:

::requires "oodPlain.cls"

Methods:

The class methods of DlgUtil are listed in the following table:

Table 10-2. Methods of the DlgUtil class

Method......description
colorRef (Class Method)colorRef
comCtl32Version (Class Method)comCtl32Version
getBValue (Class Method)getBValue
getGValue (Class Method)getGValue
getRValue (Class Method)getRValue
getSystemMetrics (Class Method)getSystemMetrics
hiWord (Class Method)hiWord
loWord (Class Method)loWord
or (Class Method)or
and (Class Method)and
version (Class Method)version

version (Class Method)

                      +-Full----+
>>-.DlgUtil~version(--------------)------------------------><
                      +-Short---+

Returns the ooDialog version string.

Arguments:

There are no arguments for this method.

format

A keyword indicating the format of the returned version string. Only the first letter is needed and case is not significant. Any unrecognized keyword is ignored and the default format is used. The format for each keyword is as follows:

Full

A string specifying the version of ooDialog. This is the default. The string has the format: ooDialog Version x.x.x.SS (an ooRexx Windows Extension) where x.x.x is the ooRexx interpreter version and SS is the Subversion revision number of the build. The actual version string might look like: ooDialog Version 4.0.0.3734 (an ooRexx Windows Extension)

Short

Only the x.x.x.SS part of the full version string is returned.

Return value:

A string in one of the formats specified above.

Example:

v = .DlgUtil~version
say v
say

if .DlgUtil~version("SHORT") < 4.1.0.0000 then do
  say 'Too bad, you are still running ooRexx 4.0.0'
end
else do
  say 'Great you have upgraded past ooRexx 4.1.0'
end

::requires 'oodPlain.cls'

/* On the screen you might see:

ooDialog Version 4.0.0.3768 (an ooRexx Windows Extension)

Too bad, you are still running ooRexx 4.0.0

*/

comCtl32Version (Class Method)

                              +-Short---+
>>-.DlgUtil~comCtl32Version(--------------)----------------><
                              +-Number--+
                              +-OS------+
                              +-Full----+

Use this method to determine the version of the Common Controls Library used by ooDialog on the current system.

Arguments:

The single argument is:

format

A keyword indicating the format of the returned version string. Only the first letter is needed and case is not significant. Any unrecognized keyword is ignored and the default format is used. The format for each keyword is as follows:

Short

The version number, for instance 4.72 or 6.0. This is the default.

Number

This is an alias for short.

OS

The minimum operating system that can be expected to be compatible with the libray. Earlier versions of the common control library were also distributed with Internet Explorer and so an OS part of say, W98 / IE 4.01 would indicate that the current common control library supports all the features available on Windows 98 or with Internet Explorer 4.01.

Full

The full format string in the format comctl32.dll version 6.0 (XP). Where the 6.0 is the number part and XP is the OS part.

Return value:

This method returns a string in one of the formats described above.

Example:

In the following example, the programmer repositions the dialog controls under certain conditions. In Windows XP and later, this task is more accurate if the getIdealSize() method of the ButtonControl class is used. However, the programmer needs the application to also run on Windows 2000. He uses the comCtl32Version() method to determine if the getIdealSize method is available. If it is not available he uses an alternative, but less accurate method to reposition the controls.

::method repositionControls

  if .DlgUtil~comCtl32Version < 6.0 then return self~doW2KReposition

  size = self~getButtonControl(IDC_CHECK_TWO)~getIdealSize
  if size == .nil then return .false

  -- do the repositioning

return .true
An alternative way to achieve the same thing might be:
::method repositionControls

  if .DlgUtil~comCtl32Version('O') == "XP" then return self~doXPReposition

  -- Do the less accurate repositioning
  ...

return .true

loWord (Class Method)

>>-.DlgUtil~loWord(--param--)------------------------------><

The Windows API often packs two values into a single number. One value in the low-order word and the other value in the high-order word. In ooDialog this is most often seen in the arguments passed to event notification methods. This utility method is used to extract the low-order word from a number.

Arguments:

The arguments are:

param

The number whose low-order word is needed.

Return value:

The return is the low-order word portion of the number.

Example:

A common place in the Windows API where two values are packed into a single number is where the API deals with position. This example shows how to extract the x and y position coordinates of a dialog after it has been moved. The example is complete, it can be cut and pasted into a file and will execute as is.


  dlg = .MovingDialog~new
  dlg~createCenter(100, 60, "Move Me")
  dlg~execute("SHOWTOP")

::requires 'ooDialog.cls'

::class 'MovingDialog' subclass UserDialog

::method init
  forward class (super) continue

  self~connectMove(onMove)

::method onMove
  use arg unUsed, posInfo

  -- Look at our message queue to see if the next message in the queue is also
  -- onMove.  If so, just return.
  msg = self~peekDialogMessage
  if msg~left(6) = "ONMOVE" then return

  -- Now, we should be done moving, print out where we are.
  x = .DlgUtil~loWord(posInfo)
  y = .DlgUtil~hiWord(posInfo)
  say 'At coordinate (' x',' y' ) on the screen. (In pixels.)'

hiWord (Class Method)

>>-.DlgUtil~hiWord(--param--)------------------------------><

The Windows API often packs two values into a single number. One value in the low-order word and the other value in the high-order word. In ooDialog this is most often seen in the arguments passed to event notification methods. This utility method is used to extract the high-order word from a number.

Arguments:

The arguments are:

param

The number whose high-order word is needed.

Return value:

The return is the high-order word portion of the number.

Example:

See the loWord() example.

or (Class Method)

                  +-,-------+
                  V         |
>>--.DlgUtil~or(----number--+--)-----------------------------------><

Combines any number of numerical values into a single number by oring the individual numbers together. This is the typical or operation used by assembly and C programmer's. The ooDialog programmer does not need to understand the concept to use this method. Some arguments to some methods in the ooDialog framework can take a value that is a combination of some individual flags. The or method is provided to construct this combination.

Details:

Raises syntax errors when incorrect arguments are detected.

Arguments:

There is no restriction on the number of arguments to this method, other than each argument must represent a whole number.

As a convenience, the whole numbers can also be specified as a string with the following format: 0x followed by a series of hexidecimal digits with no spaces. Such as "0xff12abc9" or "0x1" or "0x00000080". This makes it easy to look up and use the value of a flag directly. For instance looking up the value of ILC_COLOR24, one would see it is 0x00000018. This value could be used directly in the or() method. Case is not significant in the string.

Return value:

The return value is a number that is the result of combining all the individual arguments together.

Example:

One method that has an argument that can be the result of combining a number of flags is the create() method of the .ImageList class. This is how the or method might be used

  flags = .DlgUtil~or(.Image~toID(ILC_COLOR24), .Image~toID(ILC_MASK))

  -- Create an empty .ImageList object:
  imageList = .ImageList~create(.Size~new(61, 46), flags, 10, 10);

The following is equivalent to the above example:

  flags = .DlgUtil~or(0x00000018, 0x00000001)

  -- Create an empty .ImageList object:
  imageList = .ImageList~create(.Size~new(61, 46), flags, 10, 10);

To round out the examples a little:

  flags = .DlgUtil~or(.Image~toID(ILC_COLOR24), .Image~toID(ILC_MASK))
  say "Flags value:" flags

  flags = .DlgUtil~or(0x00000018, 0x00000001)
  say "Flags value:" flags

::requires 'oodDialog.cls'

/* Output would be:

     Flags value: 25
     Flags value: 25
*/

and (Class Method)

>>--.DlgUtil~and(--number1-,-number2--)----------------------------><

Combines two numbers into a single number by anding the individual numbers together. This is the typical and operation used by assembly and C programmer's. The typical ooDialog programmer would have no need of the method. It is provided as a convenience for use in sophisticated ooDialog programs.

The normal use of an and operation in ooDialog programs is to extract the low or high words from an argument returned from the operating system. The addition of the loWord() and hiWord() methods to the ooDialog framework have eliminated the reason for this usage.

Details:

Raises syntax errors when incorrect arguments are detected.

Arguments:

The required two arguments are the whole numbers to be anded together.

As a convenience, the whole numbers can also be specified as a string with the following format: 0x followed by a series of hexidecimal digits with no spaces. Such as "0xff12abc9" or "0x1" or "0x00000080".

Return value:

The return value is the number that is the result of anding the two arguments together.

Example:

The following example is part of a generic method in an application that returns the text of an edit control. The application is a complex one and has many edit controls that are read only. The text for read only controls is ignored. The method returns .nil for read only controls to differentiate the difference between a read only control and a control that has the empty string.

The value of the ES_READONLY style is 0x0800.


::method getEditText private
  use strict arg control

  -- If the control is read only, we just return .nil
  if .DlgUtil~and(control~getStyleRaw, 0x0800) <> 0 then return .nil

  ...

getSystemMetrics (Class Method)

>>--.DlgUtil~GetSystemMetrics(--index--)-----------------------><

Obtains the system metric value for the given index.

Arguments:

The only argument is:

index

The numeric index of the system metric.

Good documentation on the system metrics is found in the MSDN Library under the GetSystemMetrics function. This documentation contains both the numeric value of the different indexes and information on what is returned for each index. The documentation is easy to found using a Google search of "GetSystemMetrics MSDN library"

Return value:

The return value is dependent on the index queried. Consult the MSDN library for information on the returned values.

Note: The OS will return 0 if an invalid index is used. Hoever, the return value for some indexes is also 0. The programmer will need to determine from the context if 0 is an error return or not.

Example:

The following code snippet is from an application where the user can have 5, 6, or more, independent dialogs open at one time. One of the menu options is "Tile Dialogs." When the user selects this option all the open dialogs are "tiled."

All the open dialog objects are stored in a queue. In the onTile method, which is invoked when the user selects the menu item, each dialog is fetched in turn from the queue. Then the dialog is repositioned at an offset from the preceding dialog. It is shifted to the right the width of 2 scroll bars and shifted down the the width of the title bar. (This width is the title bar width plus the thin border around the title bar.) The height of the thin border, the height of the title bar, and the width of a scroll bar are all determined by querying the system metrics.

 

      ::method onTile
        expose offSetX offSetY dialogQueue

        -- SM_CXVSCROLL = 20
        -- SM_CYCAPTION = 4
        -- SM_CYBORDER  = 6

        if \ offSetX~datatype('W') then do
          scrollBarX = .DlgUtil~getSystemMetrics(20)
          titleBarY = .DlgUtil~getSystemMetrics(4)
          windowBorderY = .DlgUtil~getSystemMetrics(6)

          offSetX = 2 * scrollBarX
          offSetY = (2 * windowBorderY) + titleBarY
        end

        parse value self~getWindowRect(self~dlgHandle) with x y .

        do dlg over dialogQueue
          x += offSetX
          y += offSetY

          self~setWindowRect(dlg~dlgHandle, x, y, 0, 0, "NOSIZE")
        end