view release on metacpan or  search on metacpan

os2/OS2/OS2-Process/Process.pm  view on Meta::CPAN

=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 argument $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 interruptible 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 the L</OS2::localMorphPM, OS2::localFlashWindow, and OS2::localClipbrd classes>

=head2 Control of the PM atom tables

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

=over

=item	AddAtom($name, [$atomtable])

Returns the atom; increments the use count unless $name is a name of an
integer atom.

=item	FindAtom($name, [$atomtable])

Returns the atom if it exists, 0 otherwise (actually, croaks).

=item	DeleteAtom($name, [$atomtable])

Decrements the use count unless $name is a name of an integer atom.
When count goes to 0, association of the name to an integer is removed.
(Version with prepended underscore returns 0 on success.)

=item	AtomName($atom, [$atomtable])

Returns the name of the atom.  Integer atoms have names of format C<"#ddddd">
of variable length up to 7 chars.

=item	AtomLength($atom, [$atomtable])

Returns the length of the name of the atom.  Return of 0 means that no
such atom exists (but usually croaks in such a case).

Integer atoms always return length 6.

=item	AtomUsage($name, [$atomtable])

Returns the usage count of the atom.

=item	SystemAtomTable()

Returns central atom table accessible to any process.

=item	CreateAtomTable( [ $initial, [ $buckets ] ] )

Returns new per-process atom table.  See docs for WinCreateAtomTable(3).

=item	DestroyAtomTable($atomtable)

Dispose of the table. (Version with prepended underscore returns 0 on success.)


=back

=head2 Alerting the user

=over

os2/OS2/OS2-Process/Process.pm  view on Meta::CPAN

In particular, exactly one button should have C<BS_DEFAULT> style (e.g.,
given as C<[$button_Name]>); otherwise the message box will not have keyboard
focus!  (The only exception is the case of one button; then C<[$button_Name]>
can be replaced (for convenience) with plain C<$button_Name>.)

If text of the button contains character C<~>, the following character becomes
the keyboard accelerator for this button.  One can also get the handle
of system icons directly, so C<'SP#22'> can be replaced by
C<OS2::Process::get_pointer(22)>; see also C<SPTR_*> constants.

B<NOTE> With C<MB_NONMODAL> the program continues after displaying the
nonmodal message box.  The message box remains visible until the owner window
destroys it. Two notification messages, WM_MSGBOXINIT and WM_MSGBOXDISMISS,
are used to support this non-modality. 

=item LoadPointer($id, [$module, [$hwnd]])

Loads a handle for the pointer $id from the resources of the module
$module on desktop $hwnd.  If $module is 0 (default), loads from the main
executable; otherwise from a DLL with the handle $module.

The pointer is owned by the process, and is destroyed by
DestroyPointer() call, or when the process terminates.

=item SysPointer($id, [$copy, [$hwnd]])

Gets a handle for (a copy of) the system pointer $id (the value should
be one of C<SPTR_*> constants).  A copy is made if $copy is TRUE (the
default).  $hwnd defaults to C<HWND_DESKTOP>.

=item get_pointer($id, [$copy, [$hwnd]])

Gets (and caches) a copy of the system pointer.

=back

=head2 Constants used by OS/2 APIs

Function C<os2constant($name)> returns the value of the constant; to
decrease the memory usage of this package, only the constants used by
APIs called by Perl functions in this package are made available.

For direct access, see also the L<"EXPORTS"> section; the latter way
may also provide some performance advantages, since the value of the
constant is cached.

=head1 OS2::localMorphPM, OS2::localFlashWindow, and OS2::localClipbrd classes

The class C<OS2::localMorphPM> morphs the process to PM for the duration of
the given scope.

  {
    my $h = OS2::localMorphPM->new(0);
    # Do something
  }

The argument has the same meaning as one to OS2::MorphPM().  Calls can
nest with internal ones being NOPs.

Likewise, C<OS2::localClipbrd> class opens the clipboard for the duration
of the current scope; if TRUE optional argument is given, it would not
morph the application into PM:

  {
    my $handle = OS2::localClipbrd->new(1);	# Do not morph into PM
    # Do something with clipboard here...
  }

C<OS2::localFlashWindow> behaves similarly; see
L<FlashWindow($hwnd, $doFlash)>.

=head1 EXAMPLES

The test suite for this module contains an almost comprehensive collection
of examples of using the API of this module.

=head1 TODO

Add tests for:

	SwitchToProgram
	ClassName
	out_codepage
	out_codepage_set
	in_codepage
	in_codepage_set
	cursor
	cursor_set
	screen
	screen_set
	process_codepages
	QueryWindow
	EnumDlgItem
        WindowPtr
        WindowUShort
        SetWindowBits
        SetWindowPtr
        SetWindowULong
        SetWindowUShort
	my_type
	file_type
	scrsize
	scrsize_set

Document: InvalidateRect,
CreateFrameControls, kbdChar, kbdhChar,
kbdStatus, _kbdStatus_set, kbdhStatus, kbdhStatus_set,
vioConfig, viohConfig, vioMode, viohMode, viohMode_set, _vioMode_set,
_vioState, _vioState_set, vioFont, vioFont_set

Test: SetWindowULong/Short/Ptr, SetWindowBits. InvalidateRect,
CreateFrameControls, ClipbrdOwner_set, ClipbrdViewer_set, _ClipbrdData_set,
Alarm, FlashWindow, _MessageBox, MessageBox, _MessageBox2, MessageBox2,
LoadPointer, SysPointer, kbdChar, kbdhChar, kbdStatus, _kbdStatus_set,
kbdhStatus,  kbdhStatus_set, vioConfig, viohConfig, vioMode, viohMode,
viohMode_set, _vioMode_set, _vioState, _vioState_set, vioFont, vioFont_set

Implement SOMETHINGFROMMR.


  >But I wish to change the default button if the user enters some
  >text into an entryfield.  I can detect the entry ok, but can't
  >seem to get the button to change to default.
  >
  >No matter what message I send it, it's being ignored.