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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)