process.pm

source of perl for linux application,

Returns the "window style" flags for window handle $hwnd.

=item WindowULong($hwnd, $id), WindowPtr($hwnd, $id), WindowUShort($hwnd, $id)

Return data associated to window handle $hwnd.  $id should be one of
C<QWL_*>, C<QWP_PFNWP>, C<QWS_*> constants, or a byte offset referencing
a region (of length 4, 4, 2 correspondingly) fully inside C<0..cbWindowData-1>.
Here C<cbWindowData> is the count of extra user-specified bytes reserved
for the given class of windows.

=item WindowULong_set($hwnd, $id, $value), WindowPtr_set, WindowUShort_set

Similar to WindowULong(), WindowPtr(), WindowUShort(), but for assigning the
value $value.

=item WindowBits_set($hwnd, $id, $value, $mask)

Similar to WindowULong_set(), but will change only the bits which are
set in $mask.

=item FocusWindow()

returns the handle of the focus window.  Optional argument for specifying
the desktop to use.

=item C<FocusWindow_set($hwnd)>

set the focus window by handle.  Optional argument for specifying the desktop
to use.  E.g, the first entry in program_entries() is the C<Ctrl-Esc> list.
To show an application, use either one of

       WinShowWindow( $hwnd, 1 );
       FocusWindow_set( $hwnd );
       SwitchToProgram($switch_handle);

(Which work with alternative focus-to-front policies?)  Requires
(morphing to) PM.

Switching focus to currently-unfocused window moves the window to the
front in Z-order; use FocusWindow_set_keep_Zorder() to avoid this.

=item C<FocusWindow_set_keep_Zorder($hwnd)>

same as FocusWindow_set(), but preserves the Z-order of windows.

=item C<ActiveWindow([$parentHwnd])>

gets the active subwindow's handle for $parentHwnd or desktop.
Returns FALSE if none.

=item C<ActiveWindow_set($hwnd, [$parentHwnd])>

sets the active subwindow's handle for $parentHwnd or desktop.  Requires (morphing to) PM.

=item C<ShowWindow($hwnd [, $show])>

Set visible/hidden flag of the window.  Default: $show is TRUE.

=item C<EnableWindowUpdate($hwnd [, $update])>

Set window visibility state flag for the window for subsequent drawing.
No actual drawing is done at this moment.  Use C<ShowWindow($hwnd, $state)>
when redrawing is needed.  While update is disabled, changes to the "window
state" do not change the appearance of the window.  Default: $update is TRUE.

(What is manipulated is the bit C<WS_VISIBLE> of the window style.)

=item C<EnableWindow($hwnd [, $enable])>

Set the window enabled state.  Default: $enable is TRUE.

Results in C<WM_ENABLED> message sent to the window.  Typically, this
would change the appearence of the window.  If at the moment of disabling
focus is in the window (or a descendant), focus is lost (no focus anywhere).
If focus is needed, it can be reassigned explicitly later.

=item IsWindowEnabled(), IsWindowVisible(), IsWindowShowing()

these functions take $hwnd as an argument.  IsWindowEnabled() queries
the state changed by EnableWindow(), IsWindowVisible() the state changed
by ShowWindow(), IsWindowShowing() is true if there is a part of the window
visible on the screen.

=item C<PostMsg($hwnd, $msg, $mp1, $mp2)>

post message to a window.  The meaning of $mp1, $mp2 is specific for each
message id $msg, they default to 0.  E.g.,

  use OS2::Process qw(:DEFAULT WM_SYSCOMMAND WM_CONTEXTMENU
		      WM_SAVEAPPLICATION WM_QUIT WM_CLOSE
		      SC_MAXIMIZE SC_RESTORE);
  $hwnd = process_hentry()->{owner_hwnd};
  # Emulate choosing `Restore' from the window menu:
  PostMsg $hwnd, WM_SYSCOMMAND, MPFROMSHORT(SC_RESTORE); # Not immediate

  # Emulate `Show-Contextmenu' (Double-Click-2), two ways:
  PostMsg ActiveWindow, WM_CONTEXTMENU;
  PostMsg FocusWindow, WM_CONTEXTMENU;

  /* Emulate `Close' */
  PostMsg ActiveWindow, WM_CLOSE;

  /* Same but with some "warnings" to the application */
  $hwnd = ActiveWindow;
  PostMsg $hwnd, WM_SAVEAPPLICATION;
  PostMsg $hwnd, WM_CLOSE;
  PostMsg $hwnd, WM_QUIT;

In fact, MPFROMSHORT() may be omitted above.

For messages to other processes, messages which take/return a pointer are
not supported.

=item C<MP*()>

The functions MPFROMSHORT(), MPVOID(), MPFROMCHAR(), MPFROM2SHORT(),
MPFROMSH2CH(), MPFROMLONG() can be used the same way as from C.  Use them
to construct parameters $m1, $m2 to PostMsg().

These functions are not exported by default.

=item C<$eh = BeginEnumWindows($hwnd)>

starts enumerating immediate child windows of $hwnd in z-order.  The
enumeration reflects the state at the moment of BeginEnumWindows() calls;
use IsWindow() to be sure.  All the functions in this group require (morphing to) PM.

=item C<$kid_hwnd = GetNextWindow($eh)>

gets the next kid in the list.  Gets 0 on error or when the list ends.

=item C<EndEnumWindows($eh)>

End enumeration and release the list.

=item C<@list = ChildWindows([$hwnd])>

returns the list of child windows at the moment of the call.  Same remark
as for enumeration interface applies.  Defaults to HWND_DESKTOP.
Example of usage:

  sub l {
    my ($o,$h) = @_;
    printf ' ' x $o . "%#x\n", $h;
    l($o+2,$_) for ChildWindows $h;
  }
  l 0, $HWND_DESKTOP

=item C<IsWindow($hwnd)>

true if the window handle is still valid.

=item C<QueryWindow($hwnd, $type)>

gets the handle of a related window.  $type should be one of C<QW_*> constants.

=item C<IsChild($hwnd, $parent)>

return TRUE if $hwnd is a descendant of $parent.

=item C<WindowFromId($hwnd, $id)>

return a window handle of a child of $hwnd with the given $id.

  hwndSysMenu = WinWindowFromID(hwndDlg, FID_SYSMENU);
  WinSendMsg(hwndSysMenu, MM_SETITEMATTR,
      MPFROM2SHORT(SC_CLOSE, TRUE),
      MPFROM2SHORT(MIA_DISABLED, MIA_DISABLED));

=item C<WindowFromPoint($x, $y [, $hwndParent [, $descedantsToo]])>

gets a handle of a child of $hwndParent at C<($x,$y)>.  If $descedantsToo
(defaulting to 1) then children of children may be returned too.  May return
$hwndParent (defaults to desktop) if no suitable children are found,
or 0 if the point is outside the parent.

$x and $y are relative to $hwndParent.

=item C<EnumDlgItem($dlgHwnd, $type [, $relativeHwnd])>

gets a dialog item window handle for an item of type $type of $dlgHwnd
relative to $relativeHwnd, which is descendant of $dlgHwnd.
$relativeHwnd may be specified if $type is EDI_FIRSTTABITEM or
EDI_LASTTABITEM.

The return is always an immediate child of hwndDlg, even if hwnd is
not an immediate child window.  $type may be

=over

=item EDI_FIRSTGROUPITEM

First item in the same group.

=item EDI_FIRSTTABITEM

First item in dialog with style WS_TABSTOP. hwnd is ignored.

=item EDI_LASTGROUPITEM

Last item in the same group.

=item EDI_LASTTABITEM

Last item in dialog with style WS_TABSTOP. hwnd is ignored.

=item EDI_NEXTGROUPITEM

Next item in the same group. Wraps around to beginning of group when
the end of the group is reached.

=item EDI_NEXTTABITEM

Next item with style WS_TABSTOP. Wraps around to beginning of dialog
item list when end is reached.

=item EDI_PREVGROUPITEM

Previous item in the same group. Wraps around to end of group when the
start of the group is reached. For information on the WS_GROUP style,
see Window Styles.

=item EDI_PREVTABITEM

Previous item with style WS_TABSTOP. Wraps around to end of dialog
item list when beginning is reached.

=back

=item DesktopWindow()

gets the actual window handle of the PM desktop; most APIs accept the
pseudo-handle C<HWND_DESKTOP> instead.  Keep in mind that the WPS
desktop (one with WindowText() being C<"Desktop">) is a different beast?!

=item TopLevel($hwnd)

gets the toplevel window of $hwnd.

=item ResetWinError()

Resets $^E.  One may need to call it before the C<Win*>-class APIs which may
return 0 during normal operation.  In such a case one should check both
for return value being zero and $^E being non-zero.  The following APIs
do ResetWinError() themselves, thus do not need an explicit one:

  WindowPtr
  WindowULong
  WindowUShort
  WindowTextLength
  ActiveWindow
  PostMsg

This function is normally not needed.  Not exported by default.

=back

=head2 Control of the PM data

=over

=item ActiveDesktopPathname()

gets the path of the directory which corresponds to Desktop.

=item 	InvalidateRect

=item	CreateFrameControls

=back

=head2 Control of the PM clipboard

=over

=item ClipbrdText()

gets the content of the clipboard.  An optional argument is the format
of the data in the clipboard (defaults to C<CF_TEXT>).  May croak with error
C<PMERR_INVALID_HWND> if no data of given $fmt is present.

Note that the usual convention is to have clipboard data with
C<"\r\n"> as line separators.  This function will only work with clipboard
data types which are delimited by C<"\0"> byte (not included in the result).

=item ClipbrdText_2byte

Same as ClipbrdText(), but will only work with clipboard
data types which are collection of C C<shorts> delimited by C<0> short
(not included in the result).

=item ClipbrdTextUCS2le

Same as ClipbrdText_2byte(), but will assume that the shorts represent
an Unicode string in I<UCS-2le> format (little-endian 2-byte representation
of Unicode), and will provide the result in Perl internal C<utf8> format
(one short of input represents one Perl character).

Note that Firefox etc. export their selection in unicode types of this format.

=item ClipbrdText_set($txt, [$no_convert_nl, [$fmt, [$fmtinfo, [$hab] ] ] ] )

sets the text content of the clipboard after removing old contents.  Unless the
optional argument  $no_convert_nl is TRUE, will convert newlines to C<"\r\n">.  Another optional
argument $fmt is the format of the data in the clipboard (should be an
atom, defaults to C<CF_TEXT>).  Other arguments are as for C<ClipbrdData_set>.
Croaks on failure.

=item	ClipbrdFmtInfo( [$fmt, [ $hab ] ])

returns the $fmtInfo flags set by the application which filled the
format $fmt of the clipboard.  $fmt defaults to C<CF_TEXT>.

=item	ClipbrdOwner( [ $hab ] )

Returns window handle of the current clipboard owner.

=item	ClipbrdViewer( [ $hab ] )

Returns window handle of the current clipboard viewer.

=item	ClipbrdData( [$fmt, [ $hab ] ])

Returns a handle to clipboard data of the given format as an integer.
Format defaults to C<CF_TEXT> (in this case the handle is a memory address).

Clipboard should be opened before calling this function.  May croak with error
C<PMERR_INVALID_HWND> if no data of given $fmt is present.

The result should not be used after clipboard is closed.  Hence a return handle 
of type C<CLI_POINTER> may need to be converted to a string and stored for
future usage.  Use MemoryRegionSize() to get a high estimate on the length
of region addressed by this pointer; the actual length inside this region
should be obtained by knowing particular format of data.  E.g., it may be
0-byte terminated for string types, or 0-short terminated for wide-char string
types.

=item	OpenClipbrd( [ $hab ] )

claim read access to the clipboard.  May need a message queue to operate.
May block until other processes finish dealing with clipboard.

=item	CloseClipbrd( [ $hab ] )

Allow other processes access to clipboard.
Clipboard should be opened before calling this function.

=item	ClipbrdData_set($data, [$convert_nl, [$fmt, [$fmtInfo, [ $hab] ] ] ] )

Sets the clipboard data of format given by atom $fmt.  Format defaults to
CF_TEXT.

$fmtInfo should declare what type of handle $data is; it should be either
C<CFI_POINTER>, or C<CFI_HANDLE> (possibly qualified by C<CFI_OWNERFREE>
and C<CFI_OWNERDRAW> flags).  It defaults to C<CFI_HANDLE> for $fmt being
standard bitmap, metafile, and palette (undocumented???) formats;
otherwise defaults to C<CFI_POINTER>.  If format is C<CFI_POINTER>, $data
should contain the string to copy to clipboard; otherwise it should be an
integer handle.

If $convert_nl is TRUE (the default), C<"\n"> in $data are converted to
C<"\r\n"> pairs if $fmt is C<CFI_POINTER> (as is the convention for text
format of the clipboard) unless they are already in such a pair.

=item	_ClipbrdData_set($data, [$fmt, [$fmtInfo, [ $hab] ] ] )

Sets the clipboard data of format given by atom $fmt.  Format defaults to
CF_TEXT.  $data should be an address (in givable unnamed shared memory which
should not be accessed or manipulated after this call) or a handle in a form
of an integer.

$fmtInfo has the same semantic as for ClipbrdData_set().

=item	ClipbrdOwner_set( $hwnd, [ $hab ] )

Sets window handle of the current clipboard owner (window which gets messages
when content of clipboard is retrieved).

=item	ClipbrdViewer_set( $hwnd, [ $hab ] )

Sets window handle of the current clipboard owner (window which gets messages
when content of clipboard is changed).

=item	ClipbrdFmtNames()

Returns list of names of formats currently available in the clipboard.

=item	ClipbrdFmtAtoms()

Returns list of atoms of formats currently available in the clipboard.

=item	EnumClipbrdFmts($fmt [, $hab])

Low-level access to the list of formats currently available in the clipboard.
Returns the atom for the format of clipboard after $fmt.  If $fmt is 0, returns
the first format of clipboard.  Returns 0 if $fmt is the last format.  Example:

  {
    my $h = OS2::localClipbrd->new('nomorph');
    my $fmt = 0;
    push @formats, AtomName $fmt
      while $fmt = EnumClipbrdFmts $fmt;
  }

Clipboard should be opened before calling this function.  May croak if
no format is present.

=item	EmptyClipbrd( [ $hab ] )

Remove all the data handles in the clipboard.  croak()s on failure.
Clipboard should be opened before calling this function.

Recommended before assigning a value to clipboard to remove extraneous
formats of data from clipboard.

=item ($size, $flags) = MemoryRegionSize($addr, [$size_lim, [ $interrupt ]])

$addr should be a memory address (encoded as integer).  This call finds
the largest continuous region of memory belonging to the same memory object
as $addr, and having the same memory flags as $addr. $flags is the value of
the memory flag of $addr (see docs of DosQueryMem(3) for details).  If
optional argumetn $size_lim is given, the search is restricted to the region
this many bytes long (after $addr).

($addr and $size are rounded so that all the memory pages containing
the region are inspected.)  Optional argument $interrupt (defaults to 1)
specifies whether region scan should be interruptable by signals.

=back

Use class C<OS2::localClipbrd> to ensure that clipboard is closed even if
the code in the block made a non-local exit.

See L<"OS2::localMorphPM and OS2::localClipbrd classes">.

=head2 Control of the PM atom tables

Low-level methods to access the atom table(s).  $atomtable defaults to