Ilya Zakharevich > OS2-WinObject-0.02 > OS2::WinObject

Download:
os2/OS2-WinObject-0.02.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.02   Source  

NAME ^

OS2::WinObject - Perl extension for access the subset of Win* API for dealing with WPS objects.

SYNOPSIS ^

  use OS2::WinObject ':all';

  $desktop = QueryObject '<WP_DESKTOP>';
  OpenObject $desktop, OPEN_SETTINGS, 1
    or die "Can't open DESKTOP settings notebook: $!";
  $w = SysValue 'CXSCREEN';
  ($x,$y,$w,$h,$fl,$b,$s) = WindowPos QueryDesktopWindow;
  $p = ActiveDesktopPathname;
  $p = ObjectPath $desktop;

DESCRIPTION ^

Most reasonable things to do with WPS objects require access via the SOM/DSOM subsystem. However, Win* API contains some (very primitive) means to deal with objects via their handles, delegating the actual work to WPS.

When choosing these functions, the principal target was completeness; many of these function are useless except in extremely bizzare circumstances.

EXPORT

None by default.

Exportable constants

  CO_FAILIFEXISTS
  CO_REPLACEIFEXISTS
  CO_UPDATEIFEXISTS
  OPEN_AUTO
  OPEN_BATTERY
  OPEN_CONTENTS
  OPEN_DEFAULT
  OPEN_DETAILS
  OPEN_HELP
  OPEN_PALETTE
  OPEN_PROMPTDLG
  OPEN_RUNNING
  OPEN_SETTINGS
  OPEN_STATUS
  OPEN_TREE
  OPEN_USER
  PMERR_INVALID_FLAG
  PMERR_INVALID_HPTR
  PMERR_INVALID_HWND
  PMERR_INV_HDC
  PMERR_PARAMETER_OUT_OF_RANGE
  PMERR_WPDSERVER_IS_ACTIVE
  PMERR_WPDSERVER_NOT_STARTED
  SWP_ACTIVATE
  SWP_DEACTIVATE
  SWP_EXTSTATECHANGE
  SWP_FOCUSACTIVATE
  SWP_FOCUSDEACTIVATE
  SWP_HIDE
  SWP_MAXIMIZE
  SWP_MINIMIZE
  SWP_MOVE
  SWP_NOADJUST
  SWP_NOAUTOCLOSE
  SWP_NOREDRAW
  SWP_RESTORE
  SWP_SHOW
  SWP_SIZE
  SWP_ZORDER

Exportable functions (similar to C)

When accessing the following functions from Perl, prefix Win should be removed.

  HOBJECT WinCopyObject (HOBJECT hObjectofObject, HOBJECT hObjectofDest,
    ULONG ulReserved {SANE DEFAULT})
  HOBJECT WinCreateObject (PCSZ pszClassName, PCSZ pszTitle, PCSZ pszSetupString,
    PCSZ pszLocation, ULONG ulFlags)
  BOOL WinDeregisterObjectClass (PCSZ pszClassName)
  BOOL WinDestroyObject (HOBJECT hObject)
  BOOL WinEnumObjectClasses (POBJCLASS pObjClass, PULONG pulSize)
  BOOL WinFreeFileIcon (HPOINTER hptr)
  BOOL WinIsSOMDDReady (void )
  BOOL WinIsWPDServerReady (void )
  HPOINTER WinLoadFileIcon (PCSZ pszFileName, BOOL fPrivate)
  HOBJECT WinMoveObject (HOBJECT hObjectofObject, HOBJECT hObjectofDest,
    ULONG ulReserved {SANE DEFAULT})
  BOOL WinOpenObject (HOBJECT hObject, ULONG ulView, BOOL fFlag)
  BOOL WinQueryActiveDesktopPathname (PSZ pszPathName, ULONG ulSize)
  BOOL WinQueryDesktopBkgnd (HWND hwndDesktop, PDESKTOP pdsk)
  HWND WinQueryDesktopWindow (HAB hab {SANE DEFAULT}, HDC hdc {SANE DEFAULT})
  HOBJECT WinQueryObject (PCSZ pszObjectID)
  BOOL WinQueryObjectPath (HOBJECT hobject, PSZ pszPathName, ULONG ulSize)
  HWND WinQueryObjectWindow (HWND hwndDesktop {SANE DEFAULT})
  LONG WinQuerySysValue(LONG iSysValue, HWND hwndDesktop {SANE DEFAULT})
  BOOL WinQueryWindowPos (HWND hwnd, PSWP pswp)
  BOOL WinRegisterObjectClass (PCSZ pszClassName, PCSZ pszModName)
  BOOL WinReplaceObjectClass (PCSZ pszOldClassName, PCSZ pszNewClassName,
    BOOL fReplace)
  ULONG WinRestartSOMDD (BOOL fState)
  ULONG WinRestartWPDServer (BOOL fState)
  BOOL WinRestoreWindowPos (PCSZ pszAppName, PCSZ pszKeyName, HWND hwnd)
  BOOL WinSaveObject (HOBJECT hObject, BOOL fAsync)
  BOOL WinSaveWindowPos (HSAVEWP hsvwp, PSWP pswp, ULONG cswp)
  HBITMAP WinSetDesktopBkgnd (HWND hwndDesktop, __const__ DESKTOP *pdskNew)
  BOOL WinSetFileIcon (PCSZ pszFileName, __const__ ICONINFO *pIconInfo)
  BOOL WinSetMultWindowPos (HAB hab, __const__ SWP *pswp, ULONG cswp)
  BOOL WinSetObjectData (HOBJECT hObject, PCSZ pszSetupString)
  BOOL WinSetSysValue (LONG iSysValue, LONG lValue, HWND hwndDesktop);
  BOOL WinSetWindowPos (HWND hwnd, HWND hwndInsertBehind, LONG x, LONG y,
    LONG cx, LONG cy, ULONG fl)
  BOOL WinShutdownSystem (HAB hab {SANE DEFAULT}, HMQ hmq {SANE DEFAULT})
  BOOL WinStoreWindowPos (PCSZ pszAppName, PCSZ pszKeyName, HWND hwnd)

Exportable functions (shortcuts)

The functions

  BOOL WinEnumObjectClasses (POBJCLASS pObjClass, PULONG pulSize)
  BOOL WinQueryActiveDesktopPathname (PSZ pszPathName, ULONG ulSize)
  BOOL WinQueryObjectPath (HOBJECT hobject, PSZ pszPathName, ULONG ulSize)
  BOOL WinQueryWindowPos (HWND hwnd, PSWP pswp)

have easier-to-use counterparts:

  %classDLL = ObjectClasses;
  $path = ActiveDesktopPathname;
  $path = ObjectPath($hobject);
  ($x,$y,$w,$h,$flags,$hwndBehindOf,$hwndMy,$reserved1,$reserved2)
     = WindowPos($hwnd) or die "Failure of WindowPos()";

ObjectClasses() returns a hash class => DLLname; $flags is a combination of SWP_* constants.

Note that the functions

  LONG WinQuerySysValue(LONG iSysValue, HWND hwndDesktop {SANE DEFAULT})
  BOOL WinSetSysValue (LONG iSysValue, LONG lValue, HWND hwndDesktop)

has the desktop argument at the last position, while the C counterparts have it as the first argument (to enable the default value for the desktop). The easier-to-use counterparts of these functions are

  $value = SysValue($string);
  SysValue_set($string, $value) or die "Cannot set: $^E";

here $string is one of

 SWAPBUTTON DBLCLKTIME CXDBLCLK CYDBLCLK CXSIZEBORDER CYSIZEBORDER ALARM
 CURSORRATE FIRSTSCROLLRATE SCROLLRATE NUMBEREDLISTS WARNINGFREQ NOTEFREQ
 ERRORFREQ WARNINGDURATION NOTEDURATION ERRORDURATION CXSCREEN CYSCREEN
 CXVSCROLL CYHSCROLL CYVSCROLLARROW CXHSCROLLARROW CXBORDER CYBORDER
 CXDLGFRAME CYDLGFRAME CYTITLEBAR CYVSLIDER CXHSLIDER CXMINMAXBUTTON
 CYMINMAXBUTTON CYMENU CXFULLSCREEN CYFULLSCREEN CXICON CYICON CXPOINTER
 CYPOINTER DEBUG CMOUSEBUTTONS CPOINTERBUTTONS POINTERLEVEL CURSORLEVEL
 TRACKRECTLEVEL CTIMERS MOUSEPRESENT CXBYTEALIGN CXALIGN CYBYTEALIGN
 CYALIGN DESKTOPWORKAREAYTOP DESKTOPWORKAREAYBOTTOM DESKTOPWORKAREAXRIGHT
 DESKTOPWORKAREAXLEFT NOTRESERVED EXTRAKEYBEEP SETLIGHTS INSERTMODE
 MENUROLLDOWNDELAY MENUROLLUPDELAY ALTMNEMONIC TASKLISTMOUSEACCESS
 CXICONTEXTWIDTH CICONTEXTLINES CHORDTIME CXCHORD CYCHORD CXMOTIONSTART
 CYMOTIONSTART BEGINDRAG ENDDRAG SINGLESELECT OPEN CONTEXTMENU CONTEXTHELP
 TEXTEDIT BEGINSELECT ENDSELECT BEGINDRAGKB ENDDRAGKB SELECTKB OPENKB
 CONTEXTMENUKB CONTEXTHELPKB TEXTEDITKB BEGINSELECTKB ENDSELECTKB
 ANIMATION ANIMATIONSPEED MONOICONS KBDALTERED PRINTSCREEN LOCKSTARTINPUT
 DYNAMICDRAG CSYSVALUES    

(For the documentation of these values see "Arguments to SysValue".

Exportable functions (convenience)

_hwnd($integer) creates a suitable object given the integer window handle.

Export tag

All the mentioned functions are exportable with the tag :all.

Arguments to SysValue

The meaning of the argument to SysValue() is explained in the following excerpt from the OS/2 Toolkit. Not all system values can be set with WinSetSysValue; those that can be set are marked with an asterisk (*). The actual string given to SysValue() should be stripped of the leading SV_.

SV_ALARM

(*) TRUE if the alarm sound generated by WinAlarm is enabled; FALSE if the alarm sound is disabled.

SV_ALTMNEMONIC

(*) TRUE if the mnemonic is made up of KATAKANA characters; FALSE if the mnemonic is made up of ROMAN characters.

SV_ANIMATION

(*) TRUE when animation is set on. FALSE when animation is set off.

SV_BEGINDRAG

(*) Mouse begin drag (low word=mouse message id (WM_*), high word=keyboard control code (KC_*)).

SV_BEGINDRAGKB

(*) Keyboard begin drag (low word=virtual key code (VK_*), high word=keyboard control code (KC_*)).

SV_BEGINSELECT

(*) Mouse begin swipe select (low word=mouse message id (WM_*), high word=keyboard control code (KC_*)).

SV_BEGINSELECTKB

(*) Keyboard begin swipe select (low word=virtual key code (VK_*), high word=keyboard control code (KC_*)).

SV_CICONTEXTLINES

(*) Maximum number of lines that the icon text may occupy for a minimized window.

SV_CONTEXTHELP

(*) Mouse control for pop-up menu (low word=mouse message id (WM_*), high word=keyboard control code (KC_*)).

SV_CONTEXTHELPKB

(*) Keyboard control for pop-up menu (low word=virtual key code (VK_*), high word=keyboard control code (KC_*)).

SV_CONTEXTMENU

(*) Mouse request pop-up menu (low word=mouse message id (WM_*), high word=keyboard control code (KC_*)).

SV_CONTEXTMENUKB

(*) Keyboard request pop-up menu (low word=virtual key code (VK_*), high word=keyboard control code (KC_*)).

SV_CMOUSEBUTTONS

The number of buttons on the pointing device (zero if no pointing device is installed).

SV_CTIMERS

Count of available timers.

SV_CURSORLEVEL

The cursor hide level.

SV_CURSORRATE

(*) Cursor blink rate, in milliseconds.

SV_CXBORDER

Width of the nominal-width border.

SV_CXBYTEALIGN

Horizontal count of pels for alignment.

SV_CXDBLCLK

(*) Width of the pointing device double-click sensitive area. The default is the system-font character width.

SV_CXDLGFRAME

Width of the dialog-frame border.

SV_CXFULLSCREEN

Width of the client area when the window is full screen.

SV_CXHSCROLLARROW

Width of the horizontal scroll-bar arrow bit maps.

SV_CXHSLIDER

Width of the horizontal scroll-bar thumb.

SV_CXICON

Icon width.

SV_CXICONTEXTWIDTH

(*) Maximum number of characters per line allowed in the icon text for a minimized window.

SV_CXMINMAXBUTTON

Width of the minimize/maximize buttons.

SV_CXMOTIONSTART

(*) The number of pels that a pointing device must be moved in the horizontal direction, while the button is depressed, before a WM_BUTTONxMOTIONSTR message is sent.

SV_CXPOINTER

Pointer width.

SV_CXSCREEN

Width of the screen.

SV_CXSIZEBORDER

(*) Width of the sizing border.

SV_CXVSCROLL

Width of the vertical scroll-bar.

SV_CYBORDER

Height of the nominal-width border.

SV_CYBYTEALIGN

Vertical count of pels for alignment.

SV_CYDBLCLK

(*) Height of the pointing device double-click sensitive area. The default is half the height of the system font character height.

SV_CYDLGFRAME

Height of the dialog-frame border.

SV_CYFULLSCREEN

Height of the client area when the window is full screen (excluding menu height).

SV_CYHSCROLL

Height of the horizontal scroll-bar.

SV_CYICON

Icon height.

SV_CYMENU

Height of the single-line menu height.

SV_CYMINMAXBUTTON

Height of the minimize/maximize buttons.

SV_CYMOTIONSTART

(*) The number of pels that a pointing device must be moved in the vertical direction, while the button is depressed, before a WM_BUTTONxMOTIONSTR message is sent.

SV_CYPOINTER

Pointer height.

SV_CYSCREEN

Height of the screen.

SV_CYSIZEBORDER

(*) Height of the sizing border.

SV_CYTITLEBAR

Height of the caption.

SV_CYVSCROLLARROW

Height of the vertical scroll-bar arrow bit maps.

SV_CYVSLIDER

Height of the vertical scroll-bar thumb.

SV_DBLCLKTIME

(*) Pointing device double-click time, in milliseconds.

SV_DEBUG

FALSE indicates this is not a debug system.

SV_ENDDRAG

(*) Mouse end drag (low word=mouse message id (WM_*), high word=keyboard control code (KC_*)).

SV_ENDDRAGKB

(*) Keyboard end drag (low word=virtual key code (VK_*), high word=keyboard control code (KC_*)).

SV_ENDSELECT

(*) Mouse select or end swipe select (low word=mouse message id (WM_*), high word=keyboard control code (KC_*)).

SV_ENDSELECTKB

(*) Keybaord select or end swipe select (low word=virtual key code (VK_*), high word=keyboard control code (KC_*)).

SV_ERRORDURATION

(*) Duration for error alarms generated by WinAlarm.

SV_ERRORFREQ

(*) Frequency for error alarms generated by WinAlarm.

SV_EXTRAKEYBEEP

(*) When TRUE, the press of a key that does not exist on the Enhanced keyboard causes the system to generate a beep.

SV_FIRSTSCROLLRATE

(*) The delay (in milliseconds) before autoscrolling starts, when using a scroll bar.

SV_INSERTMODE

(*) TRUE if the system is in insert mode (for edit and multi-line edit controls); FALSE if in overtype mode. This system value is toggled by the system when the insert key is toggled, regardless of which window has the focus at the time.

SV_KBDALTERED

(*) Hardware ID of the newly attached keyboard.

Note: The OS/2 National Language Support is only loaded once per system IPL. The OS/2 NLS translation is based partially on the type of keyboard device attached to the system. There are two main keyboard device types: PC AT styled and Enhanced styled. Hot Plugging between these two types of devices may result in typing anomalies due to a mismatch in the NLS device tables loaded and that of the attached device. It is strongly recommended that keyboard hot plugging be limited to the device type that the system was IPL'd with. In addition, OS/2 support will default to the 101/102 key Enhanced keyboard if no keyboard or a NetServer Mode password was in use during system IPL. (See Category 4, IOCtls 77h and 7Ah for more information on keyboard devices and types.)

SV_LOCKSTARTINPUT

(*) TRUE when the type ahead function is enabled; FALSE when the type ahead function is disabled.

SV_MENUROLLDOWNDELAY

(*) The delay in milliseconds before displaying a pull down referred to from a submenu item, when the button is already down as the pointer moves onto the submenu item.

SV_MENUROLLUPDELAY

(*) The delay in milliseconds before hiding a pull down referred to from a submenu item, when the button is already down as the pointer moves off the submenu item.

SV_MONOICONS

(*) When TRUE preference is given to black and white icons when selecting which icon resource definition to use on the screen. Black and white icons may have more clarity than color icons on LCD and Plasma display screens.

SV_MOUSEPRESENT

When TRUE a mouse pointing device is attached to the system.

SV_NOTEDURATION

(*) Duration for note alarms generated by WinAlarm.

SV_NOTEFREQ

(*) Frequency for note alarms generated by WinAlarm.

SV_OPEN

(*) Mouse open (low word=mouse message id (WM_*), high word=keyboard control code (KC_*)).

SV_OPENKB

(*) Keyboard open (low word=virtual key code (VK_*), high word=keyboard control code (KC_*)).

SV_POINTERLEVEL

Pointer hide level. If the pointer level is zero, the pointer is visible. If it is greater than zero, the pointer is not visible. The WinShowPointer call is invoked to increment and decrement the SV_POINTERLEVEL, but its value cannot become negative.

SV_PRINTSCREEN

(*) TRUE when the Print Screen function is enabled; FALSE when the Print Screen function is disabled.

SV_SCROLLRATE

(*) The delay (in milliseconds) between scroll operations, when using a scroll bar.

SV_SETLIGHTS

(*) When TRUE, the appropriate light is set when the keyboard state table is set.

SV_SINGLESELECT

(*) Mouse select (low word=mouse message id (WM_*), high word=keyboard control code (KC_*)).

SV_TASKLISTMOUSEACCESS

(*) Determines whether the task list is displayed when mouse buttons 1 and 2 are pressed simultaneously, or when mouse button 2 is pressed by itself, or for no mouse gesture.

SV_TEXTEDIT

(*) Mouse begin direct name edit (low word=mouse message id (WM_*), high word=keyboard control code (KC_*)).

SV_TEXTEDITKB

(*) Keyboard begin direct name edit (low word=virtual key code (VK_*), high word=keyboard control code (KC_*)).

SV_TRACKRECTLEVEL

The hide level of the tracking rectangle (zero if visible, greater than zero if not).

SV_SWAPBUTTON

(*) TRUE if pointing device buttons are swapped. Normally, the pointing device buttons are set for right-handed use. Setting this value changes them for left-handed use. If TRUE, WM_LBUTTON* messages are returned when the user presses the right button, and WM_RBUTTON* messages are returned when the left button is pressed. Modifying this value affects the entire system. Applications should not normally read or set this value; users update this value by means of the user interface shell to suit their requirements.

SV_WARNINGDURATION

(*) Duration for warning alarms generated by WinAlarm.

SV_WARNINGFREQ

(*) Frequency for warning alarms generated by WinAlarm.

AUTHOR ^

Ilya Zakhrevich ilya@math.ohio-state.edu.

SEE ALSO ^

perl(1), SOM.

syntax highlighting: