The Windows Specific Classes

isMenu

>>-isMenu------------------------------------------------------><

Returns 1 if the associated window is a menu, otherwise 0.

items

>>-items-------------------------------------------------------><

Returns the number of menu items contained in the associated menu.

idOf

>>-idOf--(--position--)----------------------------------------><

Returns the ID of the menu item at the specified position, starting with 0.

textOf(position)

>>-textOf--(--position--)--------------------------------------><

Returns the text of the menu item at the specified position, starting with 0. A mnemonic (underscored letter) is represented by a leading ampersand (&). If the menu item contains an accelerator, it is separated by a tab.

textOf(id)

>>-textOf--(--id--)--------------------------------------------><

Returns the text of menu item id. A mnemonic is represented by a leading ampersand (&). If the menu item contains an accelerator, it is separated by a tab.

submenu

>>-submenu--(--position--)-------------------------------------><

Returns an instance of the MenuObject class that is associated with the submenu at the specified position, starting with 0. If no submenu exists at this position, the .Nil object is returned.

Example:

sub = menu~submenu(5)
    if sub \= .Nil then do
         say "Items:" sub~items
    end

findSubmenu

>>-findSubmenu--(--label--)------------------------------------><

Returns an instance of the MenuObject class that is associated with the submenu with the specified label. If the associated menu does not contain such a submenu, the .Nil object is returned.

findItem

>>-findItem--(--label--)---------------------------------------><

Returns the ID of the menu item label. If the specified label does not include an accelerator, the comparison excludes the accelerators of the menu items. If no menu item is found that matches the specified label, 0 is returned.

Example:

f = menu~findItem("&Tools" || "9"x || "Ctrl+T")
    if f \= 0 then menu~processItem(f)

processItem

>>-processItem--(--id--)---------------------------------------><

Selects the menu item id. This causes a WM_COMMAND to be sent to the window owning the menu.

dispatch

>>-dispatch(methodname--+------------+--)----------------------><
                        |  +------+  |
                        |  V      |  |
                        +----,arg-+--+

Dispatches a method with the optionally supplied arguments.

init

                    +-, "NOEVENTS"---+
>>-init(-+-ProgID-+-+----------------+-)-----------------------><
         +-CLSID--+ +-, "WITHEVENTS"-+

Instantiates an OLE object of the given ProgID or CLSID. If the creation fails, an error will be raised (see list of OLE specific errors.

The optional parameter "events" defines whether events are to be used or not. Allowed values for events are 'NOEVENTS' (the default) and 'WITHEVENTS'.

Example:

myOLEObject = .OLEObject~new("InternetExplorer.Application")

getConstant

>>-getConstant(-+--------------+-)-----------------------------><
                +-ConstantName-+

Retrieves the value of a constant that is associated with this OLE object. If no constant of that name exists, the .Nil object will be returned. You can also omit the name of the constant; this returns a stem with all known constants and their values. In this case the constant names will be prefixed with a "!" symbol.

Example 1:

myExcel = .OLEObject~new("Excel.Application")
say "xlCenter has the value" myExcel~getConstant("xlCenter")
myExcel~quit
exit

Possible output:

xlCenter has the value -4108

Example 2:

myExcel = .OLEObject~new("Excel.Application")
constants. = myExcel~getConstant
myExcel~quit

do i over constants.
  say i"="constants.i
end

Possible output:

!XLFORMULA=5
!XLMOVE=2
!XLTEXTMAC=19
...

getKnownEvents

>>-getKnownEvents----------------------------------------------><

Returns a stem with information on the events that the OLE object can create. It collects this information from the type library of the object. A type library provides the names, types, and arguments of the provided methods.

The stem provides the following information:

If no information is available, the .NIL object is returned and this OLE object does not have any events.

Example script:

myIE = .OLEObject~new("InternetExplorer.Application","NOEVENTS")
events. = myIE~getKnownEvents

if events. == .nil then
  say "Sorry, this object does not have any events."
else do
  say "The following events may occur:"
  do i = 1 to events.0
    say events.i.!NAME
  end
end

exit

Sample output:

The following events may occur:
ONTHEATERMODE
ONFULLSCREEN
ONSTATUSBAR
...

For an example of how to use events, see examples OLE\APPS\SAMP12.REX and OLE\APPS\SAMP13.REX in the SAMPLES directory.

getKnownMethods

>>-getKnownMethods---------------------------------------------><

Returns a stem with information on the methods that the OLE object supplies. It collects this information from the type library of the object. A type library provides the names, types, and arguments of the provided methods. Parts of the supplied information have only informational character as you cannot use them directly.

The stem provides the following information:

If no information is available, the .NIL object is returned.

There are mechanisms to 'hide' methods from the user, because these methods can only be used internally. It might happen that these are not hidden properly and will get displayed. Be careful with methods like:

Example script:

myOLEObject = .OLEObject~new("InternetExplorer.Application")
methods. = myOLEObject~getKnownMethods

if methods. == .nil then
  say "Sorry, no information on the methods available!"
else do
  say "The following methods are available to this OLE object:"
  do i = 1 to methods.0
    say methods.i.!NAME
  end
end

exit

Sample output:

The following methods are available to this OLE object:
GoBack
GoForward
GoHome
...

getObject

>>-getObject(Moniker-+--------+-)------------------------------><
                     +-,class-+

This is a class method that allows you to obtain an OLE object through the use of a so-called moniker or nickname (a string). A moniker is used to find out which object has to be created or, if it is already running, addressed. The moniker itself tells OLE which type of object is required. The optional parameter class can be used to specify a subclass of OLEObject, and can be used to obtain an OLE object that supports events (the 'WITHEVENTS' option will be used in this case). This method is similar to the Init method where you have to specify a ProgID or CLSID.

Example:

/* create a Word.Document by opening a certain file */
myOLEObject = .OLEObject~GetObject("C:\DOCS\HELLOWORLD.DOC")

getOutParameters

>>-getOutParameters--------------------------------------------><

Returns an array containing the results of the single out parameters of the OLE object, or the .NIL object if it does not have any. Out parameters are arguments to the OLE object that are filled in by the OLE object. As this is not possible in Rexx due to data encapsulation, the results are placed in the array mentioned above.

Example:

Consider an OLE object method with the following signature:

aMethod([in] A, [in] B, [out] sumAB)

The resulting out parameter of the method invocation will be placed in the out array at position one; the "normal" return value gets processed as usual. In this case the method will return the .NIL object:

resultTest = myOLEObject~aMethod(1, 2, .NIL)
say "Invocation result  :" resultTest
say "Result in out array:" myOLEObject~getOutParameters~at(1)

The output of this sample script will be:

The NIL object
3

Out parameters are placed in the out array in order from left to right. If the above OLE method looked like this:

aMethod([in] A, [in] B, [out] sumAB, [out] productAB),

then the out array would contain the sum of A and B at position one, and the product at position two.

unknown

>>-unknown(messagename--+----------------+--)------------------><
                        +--,messageargs--+

The unknown message is the central mechanism through which methods of the OLE object are called.

For further information, see Defining an unknown Method.

You can invoke the methods of the real OLE object by simply stating their names to the Rexx (proxy) OLE object like this:

myOLEObject~OLEMethodName

This calls the method "OLEMethodName" of the real OLE object for any message that does not exist for the Rexx OLE object by dispatching the call to the real OLE object.

If an OLE object offers a method with a name that is identical to one that is defined for OLEObject, you must call unknown directly, like this:

msgs = .array~of("Hello","World")
val = myOLEObject~unknown("Unknown",msgs)

This invokes the method "unknown" of the OLE object with two arguments, "Hello" and "World".

Parameters for the OLE object are used in the usual way, with the exception of so-called "out" parameters. Out parameters will be filled in by the OLE object itself. As this is not possible in Rexx due to data encapsulation, a special method, getOutParameters, has to be used. Specify the .Nil object for any Out parameters when invoking this method.

Type Conversion

Unlike Rexx, OLE uses strict typing of data. Conversion to and from these types is done automatically, if conversion is possible. OLE types are called variants, because they are stored in one structure that gets flagged with the type it represents. The following is a list of all variant types valid for use with OLE Automation and the Rexx objects that they are converted from or into.

* VT_ARRY and VT_BYREF are combined with any of the other variant types and never used alone. VT_ARRAY and another variant type are used for a SAFEARRAY datatype, an array of the other variant type. VT_BYREF and another variant type are used to pass the other variant type to or from an OLE object by reference. The programmer need not worry about this passing by reference, the OLE support handles this transparently.

new Class method

>>-new(valueObject-+----------+--+-------------+-)-------------><
                   +-,varType-+  +-,paramFlags-+

Instantiates a new OLEVariant object to be used as a parameter in an OLEObject method call. The first argument is the ooRexx object to be converted to a variant type for the method call. It is the object to be used in the method call. This argument is required. The varType and paramFlags arguments are optional.

The varType argument is used to specify the type of the variant that the valueObject is to be converted to. If this argument is omitted or is .nil then ooRexx will use the default conversion for the valueObject. If it is not omitted it must be a valid OLE Automation variant type and ooRexx will attempt to convert the valueObject to this variant type.

The valid variant type symbols are listed in Table OLE/Rexx Types. In addition any of those symbols can be combined with the VT_BYREF or the VT_ARRAY symbol. When symbols are combined a comma is used to separate the two symbols. This of course necessitates that the argument be quoted. Case does not matter for this argument. For example vt_bool, VT_bool, or VT_BOOL are all treated the same.

The paramFlags argument is used to specify the flags for the parameter. The flags are separated by a comma. Although any combination of valid PARAMFLAGS as defined for OLE Automation will be accepted, in practice the ooRexx programmer will probably only need to use "IN,OUT" for this argument.

The PARAMFLAGS defined for OLE Automation:

The ooRexx programmer should only use the last portion of the symbol. I.e., NONE, IN, OUT, LCID, RETVAL, OPT, HASDEFAULT, or HASCUSTOMDATA. Case also does not matter for this argument and "in,out" is equivalent to "IN,OUT"

If the paramFlags argument is omitted or .nil, (the normal case,) ooRexx will determine the flags for the parameter through its default mechanism. If the argument is not omitted, ooRexx will use the specified flags unconditionally.

manager = .oleObject~new("com.sun.star.ServiceManager", "WITHEVENTS")
cf = manager~createInstance("com.sun.star.reflection.CoreReflection")
...
classSize = .cf~forName("com.sun.star.awt.Size")

param = .OLEVariant~new(.nil, "VT_DISPATCH,VT_BYREF", "IN,OUT")

retVal = classSize~createObject(param)

!VARVALUE_

>>-!VARVALUE_--------------------------------------------------><

Returns the value object set within an instance of an OLEVariant. If the parameter in a COM method call that the OLEVariant was used for is an "out" parameter, than the value object of the instance will be the data returned by the COM object. Otherwise, the value object is that set by the ooRexx programmer.

manager = .oleObject~new("com.sun.star.ServiceManager", "WITHEVENTS")
cf = manager~createInstance("com.sun.star.reflection.CoreReflection")
...
classSize = .cf~forName("com.sun.star.awt.Size")

param = .OLEVariant~new(.nil, "VT_DISPATCH,VT_BYREF", "IN,OUT")

retVal = classSize~createObject(param)
size = param~!varValue_

!VARVALUE_=

>>-!VARVALUE_=-------------------------------------------------><

Sets the value object an instance of an OLEVariant contains.

!VARTYPE_

>>-!VARTYPE_---------------------------------------------------><

Returns the variant type specification of the OLEVariant instance.

!VARTYPE_=

>>-!VARTYPE_=--------------------------------------------------><

Sets the variant type specification of an OLEVariant instance. This serves the same purpose as the second argument to the new method and follows the same rules as specified in the documentation of the new method. I.e., the value must be a valid variant type used in OLE Automation, or .nil. If not a syntax error is raised.

!PARAMFLAGS_

>>-!PARAMFLAGS_------------------------------------------------><

Returns the parameter flags specification of the OLEVariant instance.

!PARAMFLAGS_=

>>-!PARAMFLAGS_=-----------------------------------------------><

Sets the flags specification of an OLEVariant instance. This serves the same purpose as the third argument to the new method and follows the same rules as specified in the documentation of the new method. I.e., the value must be a valid combination of PARAMFLAG types as documented for use in OLE Automation, or .nil. If not a syntax error is raised.

copy

>>-copy--(--text--)--------------------------------------------><

Empties the clipboard and copies the specified text to it.

makeArray

>>-makeArray---------------------------------------------------><

If the content of the clipboard is a string with newline characters in it, makeArray can be used to split up the string into individual lines. An array is returned containing those lines.

paste

>>-paste-------------------------------------------------------><

Retrieves the text data stored on the clipboard.

empty

>>-empty-------------------------------------------------------><

Empties the clipboard.

isDataAvailable

>>-isDataAvailable---------------------------------------------><

Returns 1 if the text data is available on the clipboard. If no data is available, 0 is returned.

init

>>-init--------------------------------------------------------><

Creates an instance of the WindowsEventLog class and loads the required function package.

open

>>-open-+---------------------------------+--------------------><
        +-(--+-----------------------+--)-+
             +-server--+-----------+-+
                       +-,--source-+

Opens the specified event log.

close

>>-close-------------------------------------------------------><

Closes an open event log.

read

>>-read--+---------------------------------------------------+-->
         |    +-FORWARDS--+                                  |
         +-(--+-----------+--,--+--------+--,--+--------+--,-+
              +-BACKWARDS-+     +-server-+     +-source-+

>--+--------------------------+--------------------------------><
   +-+-------+--,--+-----+--)-+
     +-start-+     +-num-+

Reads event log records. If the event log was not opened with the OPEN method, the event log specified by the server and source is opened and closed after processing.

write

>>-write--+-------------------------------------------------------------+-->
          |                                  +-1--+     +-0--------+    |
          +-(--+--------+--,--+--------+--,--+----+--,--+----------+--,-+
               +-server-+     +-source-+     +-0--+     +-category-+
                                             +-2--+
                                             +-4--+
                                             +-8--+
                                             +-10-+

>--+---------------------------------------+-------------------><
   | +-0--.                                |
   +-+----+--,--+------+--,--+--------+--)-+
     +-id-+     +-data-+     +-string-+

Reads event log records. If the event log was not opened with the Open method, the event log specified by the server and source is opened and closed after processing.

clear

>>-clear-+------------------------------------------------------------+-><
         +-(--+--------------------------------------------------+--)-+
              +-server--+--------------------------------------+-+
                        +-,--+--------+--+-------------------+-+
                             +-source-+  +-,--backupFileName-+

Clears the specified event log and, optionally, saves a copy of the current log file as a backup file. If the event log was not opened with the Open method, the event log specified by the server and source is opened. The event log is closed after it is cleared.

getNumber

>>-getNumber-+---------------------------------+---------------><
             +-(--+-----------------------+--)-+
                  +-server--+-----------+-+
                            +-,--source-+

Retrieves the number of records in the specified event log. If the event log was not opened with the Open method, the event log specified by the server and source is opened and closed after processing.

find

>>-find--(--title--)-------------------------------------------><

Searches for a top-level window (not a child window) on your desktop with the specified title.

If this window already exists, an instance of the WindowObject class is returned. Otherwise, .Nil is returned.

foregroundWindow

>>-foregroundWindow--------------------------------------------><

Returns an instance of the WindowObject class that is associated with the current foreground window.

windowAtPosition

>>-windowAtPosition--(--x--,--y--)-----------------------------><

Returns an instance of the WindowObject class that is associated with the window at the specified position (x,y). The coordinates are specified in screen pixels. This method does not retrieve hidden or disabled windows. If you are interested in a particular child window, use method childAtPosition.

consoleTitle

>>-consoleTitle------------------------------------------------><

Returns the title of the current console.

consoleTitle=

>>-consoleTitle=title------------------------------------------><

Sets the title of the current console.

sendTextToWindow

>>-sendTextToWindow--(--title--,--text--)----------------------><

Sends a case-sensitive text to the window with the specified title..

pushButtonInWindow

>>-pushButtonInWindow--(--title--,--text--)--------------------><

Selects the button with label text in the window with the specified title. If the button's label contains a mnemonic (underscored letter), you must specify an ampersand (&) in front of it. You can also use this method to select radio buttons and to check or uncheck check boxes.

Example:

winmgr~pushButtonInWindow("Testwindow","List &Employees")

processMenuCommand

>>-processMenuCommand--(--+-------+--,--+-------+--,------------>
                          +-title-+     +-popup-+

   +-,-------+
   V         |
>----submenu-+--,--menuItem--)---------------------------------><

Selects an item of the menu or submenu of the specified window title. You can specify as many submenus as necessary to get to the required item.

broadcastSettingChanged

>>-broadcastSettingChanged--+-----------+----------------------><
                            +-(timeOut)-+

Causes the Windows operating system to send a message, (the WM_SETTINGCHANGE message,) to every top-level window on the Desktop informing them that a system-wide setting has changed. Well-written applications will then reload any system settings that they use.

An example of one use for this might be an installer program setting an environment variable, such as the PATH. Then a call to broadcastSettingChanged would cause all open applications to update their reference to the environment, without the necessity of a reboot.

There are two variations of calling this method. When called with no arguments, the message is broadcast and returns immediately. When called with the time out parameter, the message is broadcast and does not return until every window on the Desktop has acknowledged the message, or timed out.

The problem with using a time out and waiting for acknowledgment is that, if a window is not responding, or several windows are slow to respond, it may take a very long time to return. The problem with not using a time out and returning immediately is that the caller will have no way of knowing when every window has received the message. Generally this is not a problem, but it is up to the programmer to decide how she wants to use this method.

The time out value is specified in milliseconds. For each window, the operating system will wait up to the time out for a response before going on to the next window. Typically a time out value of 5000 (5 seconds) is used, and this is the default.

The single optional argument is:

Return value:

Example:

ret = winmgr~broadcastSettingChanged(1000)

assocWindow

>>-assocWindow--(--handle--)-----------------------------------><

Assigns a new window handle to the WindowObject instance.

handle

>>-handle------------------------------------------------------><

Returns the handle of the associated window.

title

>>-title-------------------------------------------------------><

Returns the title of the window.

title=

>>-title=newTitle----------------------------------------------><

Sets a new title for the window.

wclass

>>-wclass------------------------------------------------------><

Returns the class of the window associated with the WindowObject instance.

id

>>-id----------------------------------------------------------><

Returns the numeric ID of the window.

coordinates

>>-coordinates-------------------------------------------------><

Returns the upper left and the lower right corner positions of the window in the format "left,top,right,bottom".

state

>>-state-------------------------------------------------------><

Returns information about the window state. The returned state can contain one or more of the following constants:

• "Enabled" or "Disabled"

• "Visible" or "Invisible"

• "Zoomed" or "Minimized"

• "Foreground"

restore

>>-restore-----------------------------------------------------><

Activates and displays the associated window. If the window is minimized or maximized, it is restored to its original size and position.

hide

>>-hide--------------------------------------------------------><

Hides the associated window and activates another window.

minimize

>>-minimize----------------------------------------------------><

Minimizes the associated window and activates the next higher-level window.

maximize

>>-maximize----------------------------------------------------><

Maximizes the associated window.

resize

>>-resize--(--width--,--height--)------------------------------><

Resizes the associated window to the specified width and height. The width and height are specified in screen coordinates.

enable

>>-enable------------------------------------------------------><

Enables the associated window if it was disabled.

disable

>>-disable-----------------------------------------------------><

Disables the associated window.

moveTo

>>-moveTo--(--x--,--y--)---------------------------------------><

Moves the associated window to the specified position (x,y). Specify the new position in screen pixels.

toForeground

>>-toForeground------------------------------------------------><

Makes the associated window the foreground window.

focusNextItem

>>-focusNextItem-----------------------------------------------><

Sets the input focus to the next child window of the associated window.

focusPreviousItem

>>-focusPreviousItem-------------------------------------------><

Sets the input focus to the previous child window of the associated window.

focusItem

>>-focusItem--(--wndObject--)----------------------------------><

Sets the input focus to the child window associated with the specified WindowObject instance wndObject.

Example:

The following example sets the input focus to the last child window:

 dlg = wndmgr~find("TestDialog")
    if dlg \= .Nil then do
        fChild = dlg~firstChild
        lChild = fChild~last
        dlg~focusItem(lChild)
    end

findChild

>>-findChild--(--label--)--------------------------------------><

Returns an instance of the WindowObject class associated with the child window with the specified label. If the associated window does not own such a window, the .Nil object is returned.

childAtPosition

>>-childAtPosition--(--x--,--y--)------------------------------><

Returns an instance of the WindowObject class associated with the child window at the specified client position (x,y). The coordinates that are relative to the upper left corner of the associated window must be specified in screen pixels. To retrieve top-level windows, use method windowAtPosition.

next

>>-next--------------------------------------------------------><

Returns an instance of the WindowObject class associated with the next window of the same level as the associated window. If the associated window is the last window of a level, the .Nil object is returned.

previous

>>-previous----------------------------------------------------><

Returns an instance of the WindowObject class associated with the previous window of the same level as the associated window. If the associated window is the first window of a level, the .Nil object is returned.

first

>>-first-------------------------------------------------------><

Returns an instance of the WindowObject class associated with the first window of the same level as the associated window.

last

>>-last--------------------------------------------------------><

Returns an instance of the WindowObject class associated with the last window of the same level as the associated window.

owner

>>-owner-------------------------------------------------------><

Returns an instance of the WindowObject class associated with the window that owns the associated window (parent). If the associated window is a top-level window, the .Nil object is returned.

firstChild

>>-firstChild--------------------------------------------------><

Returns an instance of the WindowObject class associated with the first child window of the associated window. If no child window exists, the .NIL object is returned.

enumerateChildren

>>-enumerateChildren-------------------------------------------><

Returns a stem that stores information about the child windows of the associated window. "Stem.0" contains the number of child windows. The returned stem contains as many records as child windows. The first record is stored at "Stem.1" continued by increments of 1. Each record contains the following entries, where each entry starts with an exclamation mark (!):

Example:

      wo = winmgr~find("TestDialog")
        enum. = wo~enumerateChildren
        do i = 1 to enum.0   /* number of children */
           say "---"
           say "Handle:" enum.i.!Handle
           say "Title:" enum.i.!Title
           say "Class:" enum.i.!Class
           say "Id:" enum.i.!Id
           say "Children:" enum.i.!Children
           say "State:" enum.i.!State
           say "Rect:" enum.i.!Coordinates
        end

sendMessage

>>-sendMessage--(--message--,--wParam--,--lParam--)------------><

Sends a message to the associated window.

sendCommand

>>-sendCommand--(--command--)----------------------------------><

Sends a WM_COMMAND message to the associated window. WM_COMMAND is sent, for example, when a button is pressed, where command is the button ID.

sendMenuCommand

>>-sendMenuCommand--(--id--)-----------------------------------><

Selects the menu item id of the associated window. Method idOf returns the ID of a menu item.

sendMouseClick

                      +-"LEFT"---+     +-"DBLCLK"-+
>>-sendMouseClick--(--+-"RIGHT"--+--,--+-"UP"-----+----,--x--,--y-->
                      +-"MIDDLE"-+     +-"DOWN"---+

>--+-----------------------------+--)--------------------------><
   |       +----------------+    |
   |       V                |    |
   +-,--"----+-LEFTDOWN---+-+--"-+
             +-RIGHTDOWN--+
             +-MIDDLEDOWN-+
             +-SHIFT------+
             +-CONTROL----+

Simulates a mouse click event in the associated window.

Arguments:

The arguments are:

sendSyscommand

>>-sendSyscommand--(--"--+-SIZE--------+--"--)-----------------><
                         +-MOVE--------+
                         +-MINIMIZE----+
                         +-MAXIMIZE----+
                         +-NEXTWINDOW--+
                         +-PREVWINDOW--+
                         +-CLOSE-------+
                         +-VSCROLL-----+
                         +-HSCROLL-----+
                         +-ARRANGE-----+
                         +-RESTORE-----+
                         +-TASKLIST----+
                         +-SCREENSAVE--+
                         +-CONTEXTHELP-+

Sends a WM_SYSCOMMAND message to the associated window. These messages are normally sent when the user selects a command in the Window menu.

Argument:

The only argument is:

pushButton

>>-pushButton--(--label--)-------------------------------------><

Selects the button with the specified label within the associated window and sends the corresponding WM_COMMAND message. If the button's label contains a mnemonic (underscored letter), you must specify an ampersand (&) in front of it. You can also use this method to select radio buttons and check or uncheck check boxes.

sendKey

>>-sendKey--(--keyName--+------------------------+--)----------><
                        +-,--+-----+--+--------+-+
                             +-alt-+  +-,--ext-+

Sends all messages (CHAR, KEYDOWN, and KEYUP) that would be sent by pressing a specific key on the keyboard. Character keys (a to z) are not case-sensitive.

If the alt argument is 1, the Alt key flag is set, which is equal to pressing the specified key together with the Alt key.

The Ext argument must be 1 if the key is an extended key, such as a right Ctrl or a right Shift.

For a list of key names, refer to Symbolic Names for Virtual Keys.

sendChar

>>-sendChar--(--character--+--------+--)-----------------------><
                           +-,--alt-+

Sends a WM_CHAR message to the associated window. If the alt argument is 1, a pressed Alt key is simulated.

sendKeyDown

>>-sendKeyDown--(--keyName--+--------+--)----------------------><
                            +-,--ext-+

Sends a WM_KEYDOWN message to the associated window. The ext argument must be 1 if the key is an extended key, such as a right Ctrl or a right Shift.

For a list of key names, refer to Symbolic Names for Virtual Keys.

sendKeyUp

>>-sendKeyUp--(--keyName--+--------+--)------------------------><
                          +-,--ext-+

Sends a WM_KEYUP message to the associated window. The ext argument must be 1 if the key is an extended key, such as a right Ctrl or a right Shift.

For a list of key names, refer to Symbolic Names for Virtual Keys.

sendText

>>-sendText--(--text--)----------------------------------------><

Sends a (case-sensitive) text to the associated window by sending a sequence of WM_CHAR, WM_KEYDOWN, and WM_KEYUP messages.

menu

>>-menu--------------------------------------------------------><

Returns an instance of the MenuObject class that refers to the menu of the associated window.

systemMenu

>>-systemMenu--------------------------------------------------><

Returns an instance of the MenuObject class that refers to the system menu of the associated window.

isMenu

>>-isMenu------------------------------------------------------><

Returns 1 if the associated window is a menu, otherwise 0.

processMenuCommand

                                       +-,-------+
                                       V         |
>>-processMenuCommand--(--+------+--,----submenu-+--,--menuItem--)-><
                          +-menu-+

Selects an item of the menu or submenu of the associated window. You can specify as many submenus as necessary to get to the required item.

addDesktopIcon

>>-addDesktopIcon--(--name--,--program--+--------------------------------+-->
                                        |                     +-0------+ |
                                        +-,--+----------+--,--+--------+-+
                                             +-iconfile-+     +-iconnr-+

>--+--------------------------------------------------------------------------+-)-><
   |                 +-"PERSONAL"-+                           +-"NORMAL"----+ |
   +-,-+---------+-,-+------------+-,-+------+-,-+--------+-,-+-------------+-+
       +-workdir-+   +-"COMMON"---+   +-args-+   +-hotkey-+   +-"MAXIMIZED"-+
                                                              +-"MINIMIZED"-+

Adds a shortcut to the Windows desktop. A sample program DESKICON.REX is provided in the ooRexx\SAMPLES directory.

addShortCut

>>-addShortCut--(--name--,--program--------------------------------------->

>--+---------------------------------------------------------------------->
   |                  +-0------+
   +-,-+----------+-,-+--------+-,-+---------+-,-+------+-,-+--------+-,-->
       +-iconfile-+   +-iconnr-+   +-workdir-+   +-args-+   +-hotkey-+

>-------------------+--)-------------------------------------------------><
    +-"NORMAL"----+ |
>---+-------------+-+
    +-"MAXIMIZED"-+
    +-"MINIMIZED"-+

Creates a shortcut within the specified folder.

addGroup

>>-addGroup(-group-)-------------------------------------------><

Adds a program group to the Programs group of the desktop. If the group already exists, it is opened. The group argument specifies the name of the program group to be added. Example:

addGroup("Object Rexx Redbook")

Return value:

addItem

>>-addItem--(--shortcut,program--------------------------------->

>--+------------------------------------------------------+----->
   +-,--+----------+--+---------------------------------+-+
        +-iconfile-+  +-,--+------------+--+----------+-+
                           +-iconnumber-+  +-,workdir-+

>--)-----------------------------------------------------------><

Adds a shortcut to a program group. The shortcut is placed into the last group used with either AddGroup or ShowGroup. Example:

AddItem("OODialog Samples", ,
"rexx oodialog\samples\sample.rex", ,
"oodialog\samples\oodialog.ico")

Return value:

deleteDesktopIcon

                                   +-"PERSONAL"-+
>>-deleteDesktopIcon--(--name--,---+------------+-)------------><
                                   +-"COMMON"---+

Deletes a shortcut from the Windows desktop that was previously created with AddDesktopIcon.

The arguments are:

Return codes:

Example:

pm = .WindowsProgramManager~new
if pm~InitCode \= 0 then exit

rc = pm~deleteDesktopIcon("MyNotepad1", ,
     "%SystemRoot%\system32\notepad.exe")
if rc \= 0 then do
  say "Error deleting shortcut: My Notepad 1"
  exit
end

exit

::requires "winsystm.cls"

deleteGroup

>>-deleteGroup(-group-)----------------------------------------><

Deletes a program group from the desktop. The group argument specifies the name of the program group to be deleted.

Return value:

deleteItem

>>-deleteItem(shortcut)----------------------------------------><

Deletes a shortcut from a program group.

Return value:

init

>>-init--------------------------------------------------------><

Creates an instance of the WindowsProgramManager class and loads the required function package.

showGroup

>>-showGroup(-group,-+-----+-)---------------------------------><
                     +-MIN-+
                     +-MAX-+

Opens a program group. The group argument specifies the name of the program group to be opened. If MIN or MAX is specified, the program group is opened minimized or maximized.

Return value:

Symbolic Names for Virtual Keys

Table 3 shows the symbolic names and the keyboard equivalents for the virtual keys used by Object Rexx.

classes_root

>>-classes_root------------------------------------------------><

Returns the handle of the root key HKEY_CLASSES_ROOT.

classes_root=

>>-classes_root=-----------------------------------------------><

This method is used by INIT to set the attribute CLASSES_ROOT to HKEY_CLASSES_ROOT. Do not modify this attribute.

close

>>-close(-+------------+-)-------------------------------------><
          +-key_handle-+

Closes a previously opened key specified by its handle. Example:

rg~close(objectrexxkey)

It can take several seconds before all data is written to disk. You can use FLUSH to empty the cache.

If key_handle is omitted, CURRENT_KEY is closed.

connect

>>-connect(-key,computer-)-------------------------------------><

Opens a key on a remote computer. This is supported only for HKEY_LOCAL_MACHINE and HKEY_USERS.

create

>>-create(-+--------+-,subkey)---------------------------------><
           +-parent-+

Adds a new named subkey to the registry and returns its handle. The parent key handle parent can be a root key or a key retrieved using OPEN. If the parent key is omitted, CURRENT_KEY is used. Example:

newkey = rg~create(rg~local_machine,"MyOwnKey")

current_key

>>-current_key-------------------------------------------------><

Returns the handle of the current key. The current key is set by INIT, CREATE, and OPEN. It is used as a default value if the key is omitted in other methods.

current_key=

>>-current_key=------------------------------------------------><

Sets the handle of the current key.

current_user

>>-current_user------------------------------------------------><

Returns the handle of the root key HKEY_CURRENT_USER.

current_user=

>>-current_user=-----------------------------------------------><

This method is used by INIT to set the attribute CURRENT_USER to HKEY_CURRENT_USER. Do not modify this attribute.

delete

>>-delete(-+------------+-,subkeyname)-------------------------><
           +-key_handle-+

Deletes a given named subkey of an open key specified by its handle and all its subkeys and values. If key_handle is omitted, CURRENT_KEY is used.

deleteValue

>>-deleteValue(-+------------+-+--------+-)--------------------><
                +-key_handle-+ +-,value-+

Deletes the named value for a given key. If key_handle is omitted, CURRENT_KEY is used. If value is blank or omitted, the default value is deleted.

flush

>>-flush(-+------------+-)-------------------------------------><
          +-key_handle-+

Forces the system to write the cache buffer of a given key to disk. If key_handle is omitted, CURRENT_KEY is flushed.

getValue

>>-getValue(-+------------+-+--------+-)-----------------------><
             +-key_handle-+ +-,value-+

Retrieves the data and type for a named value of a given key. The result is a compound variable with suffixes data and type. If key_handle is omitted, CURRENT_KEY is used. If named value is blank or omitted, the default value is retrieved. Example:

myval. = rg~getvalue(,"filesystem")        /* current key */
say "Type is" myval.type
if myval.type = "NORMAL" then say "Value is" myval.data
myval. = rg~getvalue(mykey)
say "my default value is:" myval.data
myval. = rg~getvalue(mykey,"")
say "my default value is:" myval.data

Possible types: NORMAL, EXPAND, MULTI, NUMBER, BINARY, NONE, OTHER.

init

>>-init--------------------------------------------------------><

Creates an instance of the WindowsRegistry class and loads the required external function package. The current key is set to HKEY_LOCAL_MACHINE.

list

>>-list(-+------------+-,stem.)--------------------------------><
         +-key_handle-+

Retrieves the list of subkeys for a given key in a stem variable. The name of the stem variable must include the period. The keys are returned as stem.1, stem.2, and so on. Example:

rg~LIST(objectrexxkey,orexxkeys.)
do i over orexxkeys.
say orexxkeys.i
end

listValues

>>-listValues(-+------------+-,variable.)----------------------><
               +-key_handle-+

Retrieves all value entries of a given key into a compound variable. The name of the variable must include the period. The suffixes of the compound variable are numbered starting with 1, and for each number the three values are the name (var.i.name), the data (var.i.data), and the type (var.i.type). The type is NORMAL for alphabetic values, EXPAND for expandable strings such as a path, NONE for no specified type, MULTI for multiple strings, NUMBER for a 4-byte value, and BINARY for any data format.

If key_handle is omitted, the values of CURRENT_KEY are listed.

Example:

qstem. = rg~QUERY(objectrexxkey)
rg~LISTVALUES(objectrexxkey,lv.)
do i=1 to qstem.values
say "name of value:" lv.i.name "(type="lv.i.type")"
if lv.i.type = "NORMAL" then
say "data of value:" lv.i.data
end

load

>>-load(-+------------+-,subkeyname, filename)-----------------><
         +-key_handle-+

Load creates a named subkey under the open key key_handle and loads registry data from the file filename (created by SAVE) and stores the data under the newly created subkey.

key_handle can only be HKEY_USERS or HKEY_LOCAL_MACHINE. Registry information is stored in the form of a hive - a discrete body of keys, subkeys, and values that is rooted at the top of the registry hierarchy. A hive is backed by a single file.

If key_handle is omitted, the subkey is created under HKEY_LOCAL_MACHINE.

Use UNLOAD to delete the subkey and to unlock the registry data file filename.

local_machine

>>-local_machine-----------------------------------------------><

Returns the handle of the root key HKEY_LOCAL_MACHINE.

local_machine=

>>-local_machine=----------------------------------------------><

This method is used by INIT to set the attribute LOCAL_MACHINE to HKEY_LOCAL_MACHINE. Do not modify this attribute.

open

>>-open(-+---------------+-,subkey-+--------------+-)----------><
         +-parent_handle-+         +-,-| access |-+

access:

   +-ALL-+
|--+-----+------------------------------------------------------>

   +--------------------------------------------------------------+
   V                                                              |
>----+-------+-+------+-+-------+-+---------+-+--------+-+------+-+--|
     +-WRITE-+ +-READ-+ +-QUERY-+ +-EXECUTE-+ +-NOTIFY-+ +-LINK-+

Opens a named subkey and return its handle. See CREATE for more information about parent_handle. Possible values for access are:

More than one value can be specified separated by blanks.

Notice that on Windows NT some keys require certain access rights and do not allow to open the key with all but only with certain access values.

query

>>-query--(--+------------+--)---------------------------------><
             +-key_handle-+

Retrieves information about a given key in a compound variable. The values returned are class (class name), subkeys (number of subkeys) values (number of value entries), date and time of last modification. If key_handle is omitted, CURRENT_KEY is queried. Example:

myquery. = rg~query(objectrexxkey)
say "class="myquery.class "at" myquery.date
say "subkeys="myquery.subkeys "values="myquery.values

replace

>>-replace(-+------------+-,-+------------+-,newfilename,oldfilename-)-><
            +-key_handle-+   +-subkeyname-+

Replaces the backup file of a key or subkey with a new file. Key must be an immediate descendant of HKEY_LOCAL_MACHINE or HKEY_USERS. If key_handle is omitted, the backup file of CURRENT_KEY is replaced. The values in the new file become active when the system is restarted. If subkeyname is omitted, the key and all its subkeys will be replaced.

restore

>>-restore(-+------------+-,filename-+-------------+-)---------><
            +-key_handle-+           +-,"VOLATILE"-+

Restores a key from a file. If key_handle is omitted, CURRENT_KEY is restored. Example:

rg~restore(objectrexxkey,"\objrexx\orexx")

The VOLATILE keyword creates a new memory-only set of registry information that is valid only until the system is restarted.

save

>>-save(-+------------+-,filename)-----------------------------><
         +-key_handle-+

Saves the entries of a given key into a file. If key_handle is omitted, CURRENT_KEY is saved. Example:

rg~SAVE(objectrexxkey,"\objrexx\orexx")

On a FAT system, do not use a file extension in filename.

setValue

>>-setValue(-+------------+-,-+------+-,value-+---------+-)----><
             +-key_handle-+   +-name-+        +-,NORMAL-+
                                              +-,EXPAND-+
                                              +-,MULTI--+
                                              +-,NUMBER-+
                                              +-,BINARY-+
                                              +-,NONE---+

Sets a named value of a given key. If name is blank or omitted, the default value is set. Examples:

rg~SETVALUE(objectrexxkey, ,"My default","NORMAL")
rg~SETVALUE(objectrexxkey,"Product_Name","Object Rexx")
rg~SETVALUE(objectrexxkey,"VERSION","1.0")

unload

>>-unload(-+------------+-,subkey)-----------------------------><
           +-key_handle-+

Removes a named subkey (created with LOAD) and its dependents from the registry, but does not modify the file containing the registry information. If key_handle is omitted, the subkey under CURRENT_KEY is unloaded. Unload also unlocks the registry information file.

users

>>-users-------------------------------------------------------><

Returns the handle of the root key HKEY_USERS.

users=

>>-users=------------------------------------------------------><

This method is used by INIT to set the attribute USERS to HKEY_USERS. Do not modify this attribute.